How to document Haxe code

Jens Fischer edited this page Feb 4, 2019 · 9 revisions

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

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.