Xdoc -- a DSL for Eclipse Plugin Documentation

Session Type: 
Standard [25 minutes]

Schedule info


Creating an Eclipse Plugin help can be a tedious task. Often Mylyn Wikitext is used but unfortunately, it is not well suited for code centric documentation. That is where Xdoc comes in. Xdoc is a markup language especially designed for Eclipse Plugin documentation. The tooling that comes with Xdoc features generators for Eclipse Help plugins, Eclipse Phoenix framework based websites and printable PDF documents.

The Xdoc language was designed having several goals in mind:

1. Simplicity. Flexibility in languages like Wikitext can be great, but in most cases it is not needed. It can even confuse the writers ("Do I have to use italic or bold font here?")
2. Full separation of the document's layout from its structure. Layout is always a global issue, especially when using corporate designs like the Eclipse Nova theme, for instance.
3. Validation for referenced class files. If class and/or package names change due to refactorings, the documentation has to reflect that change.
4. Support for syntax highlighting of arbitrary code chunks. When documenting DSL projects, the syntax highlighting of documented code chunks has to be definable, so it can be highlighted. Highlighting is done both, in the output files and in the Xdoc editor, so you will always get a feeling how the result will look like.
5. Intuitive language design. Writing documentation is not what software developers do for fun, or do you? So the language and the tooling itself should support the developers by all means.

In this talk the Xdoc language and tooling will be demonstrated, focusing on useful features for code centric documentation. The Xdoc language itself will be shown as well as the generated Eclipse help plugin, the generated website, and the PDF document. This way attendees will get an impression how to use Xdoc for the documentation of their Plugin Projects and how to benefit by using Xdoc.

An example of a generated Phoenix webapp can be seen here: