I’ve not posted for a while, but that doesn’t mean I’ve not been doing anything. Generally less visible stuff (yes, some porting), but I have converted Box2DFlashAS3 to use ASDoc to generate beautiful documentation.
The results are available here. For lack of a better place, this will be their permanent home, and I’ll try to keep them updated to the latest revision.
I’ve put in a few customizations to the standard ASDoc template, that I’m going to share here, as they are generally useful. You will need to customize the files a bit for your own project, though.
Examples of hidden features
The files contains an example of adding an appendix, and hiding internal namespaces, in the file ASDoc_Config_Base.xml. These features were already available, but it is not well demonstrated how to use them.
You can now mark any documenting code block with the @warning tag to emit a warning in the description. Example
If you specify a location in ASDoc_Config_Base.xml, then all classes will provide a source link to the file they were generated from. If you need finer control (e.g. per-package destinations), let me know.
Smart sort order
This ones kinda specific to Box2D, but I left it in in case anyone else can find a use for it. The index of all identifiers ignores the “b2” that all Box2D classes start with when it comes to sort order. e.g. b2AABB can be found under “A”, not “B”.
As well as generating HTML output, a “class.dot” file will be generated which is a valid GraphViz dot file. This allows you to generate class inheritance diagrams, though I haven’t implemented automatically generating it and inserting it into the HTML documentation. Inheritance is shown by an ordinary arrow, and interfaces with dotted lines.
Download the following zip, and use the files inside to replace the ones found in (a copy of) your
%FLEX_HOME%\asdoc\templates folder. Then ensure you call ASDoc using the
-templates-path switch, if you’ve used some other folder.