xDoc: generate documentation for Stratego specifications

General

Rob Vermaas is working at the moment on xDoc. Examples of generated documentation can be found at http://catamaran.labs.cs.uu.nl/docs/.

Features

• Several kinds of indices
• Pretty-printed, browsable code
• Import graphs
• XTC visualization : Stratego applications consist of a number of transformation components glued together using XTC. For program understanding it would be useful to extract the high-level data-flow graph of applications, i.e., reduce an XTC composition to a data-flow graph of component calls.

Most wanted features

If you have a nice feature that you would like, please don't hesitate to put it here.

• Category views (see message on stratego-dev)

• Index on specific attributes (related to category views). In my Stratego I'm already using caps lock TODO comments to remind me of minor issues in the code. Visual Studio also supports this. todo attributes in xdoc comments could be used for this. How to get an overview of these attributes?
  • also @see, @since, @param

• Search: some kind of interactive search method that allows finding an appropriate strategy for some task.

• Another level of documentation is documentation of the use of components. One could say this is user documentation, but in XT components are used by developers to create transformation systems just as strategy definitions in the library are. It would be useful to have an API-like presentation of components derived from the source code. A description of the component could for example be included in an xdoc comment in front of the 'main' or 'io-...' definition.

• When including tests in generated documentation, it might be clearer if all test modules are grouped into a (possibly bordered) subgraph in the dependency graphs.

• Highlight 'normal' documentation as well (instead of plain black, as the rest of the code)

Known bugs

• When certain files cannot be parsed, xDoc gives unclear error messages.

Latest sources

You can get the latest sources from the Subversion repository:

  svn checkout https://svn.strategoxt.org/repos/StrategoXT/xdoc/trunk

Related

• graph visualizations
  • Da Vinci, Graphviz, H3viewer, Walrus
• Similar documentation generation systems
  • Docbuilder, Docgen, Doc-o-matic, Imagix 4d, Javadoc, Haddock, Rigi System, The Software Bookshelf, Python Documentation Utilities Project

---

CategoryToDo^? | StrategoUtilities