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:
http://www.eclipse.org/Xtext/documentation/2_0_0/000-introduction.php

Abstract: We will describe our journey into setting up minimalistic development environment at eBay. Developers tend to include many source projects in their workspaces because they may potentially need to view, debug or otherwise tinker with included source. While viewing and debugging are possible with precompiled project libraries (jars), they don’t allow one to make modifications.

We describe dynamic projects as a way to bridge this gap by allowing developers to include projects in their binary form with an option to convert them to source projects! Like PDE but with regular JDT projects. This can be taken a step further by including only the source files being modified while having the rest of them come from their binary form. This is done by manipulating classpath which can elegantly be handled using custom classpath container.

With the dynamic projects, as much of the code is brought as binary, we run the risk of not caching the compilation issues due to source changes that affect their dependent binaries. We describe technique used to detect such binary compatibility breakage that would have gotten caught if those elements where coming as source.

Developers tend to import or create all the source projects they need before hand and compile and build everything even if they don’t edit it. There is a reason why they do that. They want to see the source, put break points, run individually, basically they want to play around with it a little bit.. This is exactly what dynamic projects enable them with i.e. cater all the facilities of a source project without the overhead of compilation. As we all know nothing comes for free, we need to build the binary and source jars for these projects and keep them available for using it in the dynamic project. Once the developers decides to edit a file, that’s when we provision the source as real source and compile it.

Let us take it to the next level, Till now we treated the whole project or a jar as a single unit. Why even that? How about we convert only the single file you want to edit. Amazing huh??. That’s what really makes the dynamic projects big. Here we let the developer modify just the files he wants to edit, and the rest of the code comes as binary from the jar files. The whole classpath complexity associated with the above two use cases is being handled inside of a custom classpath container.

Let us try to make it a little more interesting by detecting binary compatibility in this scenario. One of the biggest problems with libraries especially utility libraries is that changes to the API might break the binary compatibility. Earlier, this type of errors were be detected by compiling the consumer source code and if the consumers are binaries. In the worst case if consumers are not recompiled against the changed API,, then these errors will be manifested as run time errors there by breaking the production. Here we are addressing this issue, by detecting the binary compatibility breakage inside of the jars on the fly. Basically as and when user edits it, we signal the user if he breaks an existing consumer with his change.

Both, graphical as well as textual modeling, indisputably have their respective advantages (and disadvantages). And while a few evangelists might praise the superiority of one formalism over the other, the combination of both into a single integrated modeling tool seems to be the holy grail most modelers are indeed searching for.

While with the GMF runtime, a mature framework to develop graphical modeling tools has already been around for quite a while (which is now complemented by Graphiti), Xtext has recently closed the gap with respect to textual modeling. As such, the longed for undertaking has in theory - at least to some extent - become feasible.

Within this talk I will sketch how the integration of fully featured Xtext cell editors with support for syntax highlighting, auto-completion, scoping, and validation into a GMF-based graphical editor (and its related property sheets) can be technically achieved.