Documentation Comments

A documentation comment is a special comment that must appear immediately prior to a class, method, or field, and provides a formal description of the class, method, or field it precedes.

Documentation comments begin and end with three or more equals signs (===), as in:

===================================================
Appends a character to the end of the string.

@param c the character to append
===================================================
method append(c:Char) {
    ...
}

While only three equals signs are necessary, it is conventional to extend the row of equals signs to the end of the line.

Documentation comments consist of three parts. The summary is the first "sentence" of the content, extending from the beginning of the comment to the first period (.). The description is the entire documentation text, including the summary, up until the tags begin. The tags are a set of directives beginning with @ at the end of the documentation comment.

The summary and description are written in a variant of the standard Markdown format. Frost's Markdown implementation differs from standard Markdown in two major ways: first, all source code is assumed to be Frost code and is syntax highlighted appropriately, and second, the link syntax has been extended.

In addition to normal URL links, links within documentation comments may point to particular classes, fields, and methods. If the link target starts with "http:", "/", or "..", it will be treated as a URL. Otherwise, the compiler will attempt to resolve it as a reference to a class, field, or method. Classes may be named using their fully-qualified names, or simple name / alias if there is a use directive for them. Fields may be referenced by their simple name, if within the same class, or by an expression of the form ClassName.fieldName. Methods may be referenced in the same fashion as fields, but may also have a list of parameter types to disambiguate overloaded methods (e.g. Int64.max(Int)). The return type may also be provided to disambiguate methods with the same parameter types (e.g. readFully():String).

Frost also extends the Markdown link syntax to allow for "simple" links. Normally, you would specify the link target using a parenthesized URL after the link text, as in [Object](Object). In Frost documentation it often happens that the link text and link target are the same, so Frost allows you to omit the link target. This means you can create a link to the Object class simply by writing [Object].

Zero or more tags follow the description. Tags provide additional documentation such as parameters and return types. Supported tags include: