Xdoc is a small markup language that allows to create code centric documentation in a very convenient way. The documents can be rendered to HTML, to Eclipse Help files and to a printable PDF.
Besides the usual markup tags to emphasize text, add images and tables or create structures such as chapters, sections and the like, there are two unique features of Xdoc that I want to highlight.
First of all, it is possible to refer to Java types in a way that allows to statically validate these references. This feature comes very handy as soon as you want to describe important hooks of a framework or codebase. The references will be rendered as hyperlinks to the online Javadoc and if there is a public source repository, a second link points directly to the code.
The second interesting feature is related to code snippets in the documentation. It is often valuable to document some usage patterns for a certain class or interface by example. However, making these snippets easy to read and achieving the familiar look of an Eclipse editor with syntax coloring and the like often requires a lot of effort. Xdoc simplifies this greatly. You just define a set of keywords for a language and the renderer will take care of the highlighting for your code snippets in a consistent manner. This is a big improvement when it comes to the appearance of your help files.
To provide just a few technical details: Xdoc was build with Xtext. That is, the Eclipse editor supports all the nice features that you are already familiar with from other editors. The code generator which creates the Eclipse Help files on the fly is written in Xtend which in turn is implemented on top of Xtext 2.0. Xdoc itself was used to write the Eclipse Help for Xtext and Xtend. Actually, the Xtend Help was written before Xtend was implemented, but that's another story. The chicken or the egg? Things get a little blurry these days... Did I mention that Xtext was used to implement Xtext?
3 comments:
Looks very cool and useful! Have you heard about the new Mylyn Intent project? Xdoc seems to be well aligned with both the mission and the Xtext-based implementation of Intent. To me it seems Intent could be a good place to integrate this with other documentation-related work at Eclipse (like Mylyn WikiText, Vex, or DOT for Zest) under the Mylyn Docs project.
Hi Sebastian,
looks nice! Is it also possible to refer to elements built with another language with the codeRef construct? That way, it could be used to document arbitrary DSLs.... you could presumably even point into an Xtext grammar file. Also, in pointing to a Java type, can I also point to a method?
Cheers,
Markus
@Fabian:
Currently we don't have any plans concerning Mylyn Intent. Xdoc is strongly focused on the demands that we had in the Xtext project. Since we want to have full control over the supported set of mark-up tags and rendering, I doubt that we'll move Xdoc to Mylyn Intent as is. However, everbody who wants to do so, can create a fork and integrate it with whatever infrastructure comes to his mind.
@Markus
As of now, we don't have any plans to widen the scope of the Xdoc language. It's tailored for the specific requirements that we had in mind for documenting Xtext and Xtend. However, it's likely that we will support references to methods and fields. Since Xdoc is available at github, you can always fork it and add the possibility to refer to arbitrary elements such as Xtext grammars or other EObjects.
Post a Comment