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.
Usage
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.
@warning tag
You can now mark any documenting code block with the @warning tag to emit a warning in the description. Example
Source reference
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”.
Dotfile generation
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.
Installation
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.