Documentation Generation

Several tools are currently available for documentation generation :

  • the haxedoc tool ships with haxe and will generate basic HTML documentation based on the compiler XML output : haxedoc doc.xml. You can customize your template as explained here
  • chxDoc is a more complete Java-like documentation generator based also on the XML output
  • the hxWiki which powers haxe.org has a tool named ApiSync that will generate and synchronize the /api documentation using Haxe Wiki syntax instead of HTML, and keeping the comments that were edited/translated online.

You can write your own custom generator using folllowing information.

Writing a Custom Generator

In order to generate Haxe documentation, you can use an extra compiler commandline parameter :

haxe -xml doc.xml .....

This will store in doc.xml all the types that were compiled as part of the current compilation set.

If you want to generate XML documentation for a whole package, you can use a macro to make sure that all the files found in the given package will be compiled :

haxe -xml doc.xml --macro include('my.package') ....

The doc.xml can be later parsed with the haxe.rtti.XmlParser that will make prepare all the data structures needed to generate custom documentation :

class DocGen {
    static function main() {
        var data = sys.io.File.getContent("doc.xml");
        var doc = Xml.parse(data).firstElement();
        var parser = new haxe.rtti.XmlParser();
        parser.process(doc,"js");
    }
}

The extra parameter to the process method is the platform name (javascript in this example). It allows you to use several process calls (one per platform) in order to merge the different documentation as available for each platform. This way you'll be able to know which particular method is supported on which platform(s), such as the Http class shows.

Once this parsing/merging is done, you can access the parser.root variable which contains the root package as a TypeRoot

Haxe Std

In order to generate documentation for the whole Haxe standard library you need to download the following files :

  • all.hxml will make a compilation step for each platform
  • ImportAll.hx is a macro that will make sure that every part of the standard library will be compiled depending on the target platform

Once both downloaded you can run :

haxe all.hxml

This will given you one XML documentation file per-platform.

You can later use a tool such as haxedoc to generate the whole standard library documentation for all the platforms.

version #15755, modified 2012-12-02 11:09:32 by ppelleti