∞ /notes/visual-textual-documentation-with-dot-and-zest-in-eclipse | 2010-01-07 | graphviz programming eclipse soc zest

Visual textual documentation with DOT and Zest in Eclipse

Cross-posted to: https://fsteeg.wordpress.com/2010/01/07/visual-textual-documentation-with-dot-and-zest-in-eclipse/

Following up on my previous post, I've been playing some more with the idea of visualizing Graphviz DOT embedded in source files with Zest as tooling for a pragmatic kind of literate programming in Eclipse. My initial idea was to add the Zest graph to the Javadoc view. One problem with this is that actually using it is quite cumbersome, as it requires a patched org.eclipse.jdt.ui bundle. Another downside is that it limits the usability of this to Java documentation.

So I tweaked the Zest graph view I developed earlier to now kind of implement the same thing, but for any file in the workspace containing a DOT graph. So this still allows visualizing DOT embedded in Javadoc comments, but it might as well be used to document programs written in any obscure language somebody happened to write an Eclipse editor for, say Prolog:

Another useful thing about this approach is that it makes existing functionality from the graph view available, like a button to export the Zest graph using Graphviz. So from the source file containing a DOT graph embedded in a comment, we can export something to be used as documentation outside of Eclipse:

This approach also enables a basic way to use DOT with Zest in another place I originally thought it might be useful: wiki markup. Textual DOT graph definitions can be added to the markup and visualized with Zest while being edited in the Mylyn WikiText editor:

While I think this might actually be useful, there are some disadvantages to this more general approach. One downside is that it's basically limited to one graph per file. There are probably ways around this (e.g. with tabs), but it's different from the Javadoc view approach, where every Java element (class, method, etc.) could easily have its own graph. Another downside of having a separate view for graphs is that it distributes the documentation, while if added to the Javadoc view it's all presented in one place. But I guess that's just the price to pay for a more general solution.

Also, I'd like to mention that this is a manual kind of usage of the graph view, which can also be used to visualize DOT files created or changed programmatically (it listens to changes made to files in the workspace). That way, the view can be used to dynamically visualize program output, e.g. for debugging data structures. I believe Zest in general could be used for many awesome things in Eclipse IDEs: there's already dependency visualization, and things like watch visually while debugging (e.g. for maps), automatic visualization of method input and output, or visual call hierarchies could be really cool, in particular with Zest's animation support.

You can check out the graph view by installing the dot4zest feature from the update site at http://quui.com/updates (in the Zest category). I have added the sample files I used above to the repository (in ui/resources/lp_samples). General info (including repository location and documentation) is available on the dot4zest wiki page.