How to document Haxe code

A typical source code documentation may look like this:

/**
    This class serves as a documentation example.
    
    @see <https://haxe.org/manual/>
**/
class YourClass {
    /**
        This field serves as a documentation example.
    **/
    public var someVariable:String;

    /**
        This function serves as a markdown documentation example.
        It also uses parameter `s`.
    **/
    public function doSomething(s:String):Void { }


    /**
        This function serves as a Javadoc-styled documentation example.

        @param  url  an absolute URL giving the base location of the image
        @param  name the location of the image, relative to the url argument
    **/
    public function loadSomething(url:String, name:String):Void { }
}

Both class YourClass and its field doSomething are preceded by a block comment which describes their purpose. Everything between the opening /* and closing */ is parsed as a string, which means it can contain anything.

The documentation block comment syntax can optionally end with */ rather than **/. It also may contain a vertical column of asterisks:

/**
 * Multiple lines of documentation
 * here with a pretty column of
 * asterisks to the left.
 */

Dox supports GitHub-flavored markdown using haxe-markdown in these text blocks. This markdown rendering can be disabled with --no-markdown.

There is also support for some Javadoc-style annotations:

• @param
• @exception / @throws
• @deprecated
• @return / @returns
• @since
• @default
• @see
• @event

Hiding / showing fields

By default, all public types/fields/functions are shown.

To hide public types or fields from dox, use the metadata @:dox(hide):

@:dox(hide)
public function iAmHidden() {
   
}

To show private types or fields in dox, use the metadata @:dox(show):

@:dox(show)
private function iWasHidden() {
   
}

---

Continue reading: Generating documentation XML files using Haxe