Fractal/Cecilia ADL Component Library Documentation
Given the important lack of documentation for the developers who would like to extend the Fractal/Cecilia ADL toolchains, I am currently editing a set of documents. A part of these documents is about the design patterns that are used for building these toolchains. Another part should document the existing loader/processing components, and their assembly architecture. Albeit the first part should remain unchanged until the next revolution of these toolchains, the latter part will always be subject of modifications. For this reason, I think that we need to implement a self-documentation tool, as javadoc, but based on the ADL files. For me, this tool should at least provide the following features:
- Transformation of the ADL files to a graphical format. I think that the easiest way of doing this is generating .dot files, and using existing routed figure generators such as dot2png.
- Generation of HTML files documenting the ADLs. Obviously, we need to define a way of self-documenting the .fractal files, to obtain results a la javadoc. These HTML files should also enable hierarchical browsing, i.e. giving links to the sub-components documentations.
- Integrating the javadocs of component (loader, compiler, etc.) and task implementation classes.
- If possible, documenting the task-graph generation rules. As the task-framework is currently used, this issue may be very difficult to implement since these rules are mixed within the source code of the compiler/organizer components. Note that, we have recently developed with Matthieu a new task framework proposal that externalizes these rule definitions using a DSL. We believe that, among others, this framework may help the documentation purposes. We are currently preparing a documentation for this framework, and will soon present it to the community.
I would like to have your feedback on this subject before engaging some efforts. And maybe, someone has already developed some components that may help us.