Doc Comments

❌ Not Implemented

Line comments starting with ///, as well as block comments starting with either /** or /++ that precede a declaration will be associated with that declaration as a documentation comment. The contents of consecutive comments of this kind will get concatenated into a single documentation text.

A documentation comment starts with a paragraph that represents the short description of the documented symbol, optionally followed by a number of paragraphs that form the detailed description.

The format of these paragraphs follows an extended Markdown syntax (⚠️ TODO).

After that, any number of generic or special purpose sections may follow, denoted a line containing their caption and a trailing colon (:). The available special purpose sections are:

• Parameters: Documents each parameter of a function or mixin. The contents of this section must form a bullet list where each list entry starts with the name of a parameter enclosed into backticks, followed by a colon (:) and the documentation text for that parameter. Both, simple lists and multi-paragraph style lists, are accepted.
• Returns: Documents the return value of the function.
• Errors: Documents any errors returned by the function.
• See Also: Lists related symbols encosed in backticks as a comma separated list, used for cross-linking within the documentation.

Documentation generators typically render these sections in a different order or formatting.

In addition to the sections above, the following section names are encouraged to be used when additional standard sections are desired for a particular documentation generator:

• Authors: List of author names and/or e-mail addresses in the form Author 1 <author1@eample.org>, Author 2 <author2@example.org>
• Copyright: Copyright string
• Bugs: Description of any known bugs
• Date: Date of the documentation comment
• Deprecated: A description of the deprecation state of the symbol and possible alteratives
• Version: The version of the documented entity
• History: Version history of the documented entity
• Standards: Lists compliance with any involved standards
• Category: The name of a category in which to group the documented entity

Example

/** Computes the square of a number

	Parameters:
		- x: Number to square

	Returns:
		Returns the square of the specified number.
*/
function square(x) => x ^^ 2;