Generating documentation XML files using Haxe

Given a documented Haxe project or library, the next step is to generate documentation XML files using Haxe. This is done by using the -xml outputFile Haxe command, which works like a regular Haxe target but generates XML content instead of any real code output.

This command is complemented by the -D doc-gen compiler switch, which tells the compiler to process documentation information. It also often makes sense to add --no-output because we do not want to generate any actual output. However, we still have to provide a target command such as -neko dummy.n so the Haxe compiler knows which target we are generating documentation for.

When generating documentation for a library, it is often necessary to tell the Haxe compiler which classes to process in absence of a main-method. This can be achieved by listing classes directly on the command line such as haxe ... YourClass pack.YourOtherClass. If a full package content should be included, the --macro include('your.pack') argument can be used.

If the library can be used on multiple Haxe targets with subtle differences (such as a #if conditional compilation making certain methods (un)available), one XML per target should be generated. Dox then merges these XMLs and displays "Available on target" messages accordingly.

A typical HXML file to generate documentation may look like this:

-cp src
-D doc-gen
--macro include('pack')
--no-output
--each

--next
-xml bin/neko.xml
-neko dummy.n

--next
-xml bin/flash.xml
-swf dummy.swf

---

Continue reading: Generating HTML documentation using Dox