Describing code

lsdoc follows familiar JavaDoc and ASDoc conventions for parsing api documentation from metadata inside documentation comment blocks.

• Documentation comments
  • Code snippets
• Documentation subjects
• Tags
  • @copy
  • @deprecated
  • @param
  • @return
  • @see
• Examples

Documentation comments

Source code is described in a documentation comment block (a multi-line comment beginning with two asterisks: /** ... */) on the line above the subject:

/**
Main description.

Additional description.

@param baz parameter description
@return Return value description
*/
public function bar(baz:String):Vector.<Bat> {}

The first line in a doc comment forms the main description. Additional descriptive lines fill out the detailed description. Conventionally in generated documentation, main descriptions are rendered where a short form is necessary, and detailed descriptions are included where a long form is appropriate.

Code snippets

To include code snippets in documentation comments, use the fenced markdown syntax (with optional language hint) within the documentation comment:

/**
Main description.

Additional description, with code snippet
```as3
var f:Foo = new Foo();
for each(b:Bar in f)
{
   ⇥//...
}
```
*/

To preserve indentation, use the horizontal tab character (⇥). The loomscript compiler strips whitespace when compiling a loomlib, but the lsdoc processor will replace horizontal tab characters with a predefined indent (two spaces, by default; see the code_indent site variable).

Documentation subjects

The following constructs can be documented in LoomScript:

Tags

Tags supported by lsdoc start with the at sign (@) followed by a key, a space, and value: @key value.

Tags must always be on their own line. Each tag is described in more detail in the following sections.

@copy

Usage: @copy <source>

Re-use a description already defined by <source>, e.g. from an interface, or a parent class. The source value must be a fully qualified package (e.g. example.ExampleSuperClass), with a member named identically to the documentation subject.

/**
@copy example.ExampleSuperClass#parent_field

Additional doc comments (optional)
*/
public var my_field:String = 'foo';

@deprecated

Usage: @deprecated <since-version>

Mark the documentation subject with a deprecated label.

/**
@deprecated v2.1.3
*/
public function get legacy_property():String;

@param

Usage: @param <name⎵description>

Describe a method parameter. Include one @param line for each parameter.

The parameter name is expected as the first part of the description, separated from the rest by a single space.

/**
@param param1 The first parameter
@param rest Optional additional params
*/
public function my_method(param1:String, ...rest):void;

@return

Usage: @return <description>

Describe the return value.

/**
@return A `Dictionary` of `String` keys and `Number` values.
*/
public function get templated_property():Dictionary.<String,Number> { return null; }

@see

Usage: @see <target>

Create hyperlinks to members, types, and general web targets.

Use an octothorpe (#) to specify a member of a type. If a fully qualified type is not provided, the current type is assumed.

/**
@see #localMethod
@see example.ExampleInterface
@see example.ExampleInterface#method
@see http://foo.bar.baz
*/

Examples

Compare the source code files included with the lsdoc library and the resultant documentation on this site:

source → result