< VisDoc main page

Writing doc comments

Updated: 15 Feb 2007

Introduction

Doc comments document the use and purpose of a program, and in that sense it actually belongs to the source code. In principle you are free to choose the way you want to document your code - if the documentation just stays in the source files. But if you work in a team that is probably not the way you want to read documentation. If you want it to be useful and accessible you want an up-to-date and easy-to-navigate API documentation.

Many languages have a means to generate API documentation. Javadoc was developed by Sun Microsystems as standard tool to generate documentation for Java code, and has been embraced by Flash programmers too, perhaps because of the similarities between Java and ActionScript 2.0.

Javadoc has a few rules that are easy to learn. So few in fact, that a lot of people have made up extra rules to be more flexible in writing documentation - the @example tag for example (now part of the Javadoc proposed tags). And like others, also I have added a few tags, you can find them below under Useful tags.

If you want to have the most portable doc comments, you should use Javadoc tags only. If you want to have more flexibility in generating your documentation, you can use the tags as described below under Commonly used tags and Useful tags.

The next sections lead you through the complete Javadoc/VisDoc syntax.

Structure of doc comments

As you might know, Javadoc comments start with /** and end with */. They contain lines of text, and lines that start with tags (starting with @).

Doc comments should be written directly above the declaration of the class or class member you are describing.

/**
A comment running on
multiple lines
*/
public function update () : Void
{
    //
}

Lines in the doc comment can optionally have leading asterisks, but these are not necessary and are ignored with parsing.

/**
* A former way of writing
* doc comments
*/
public function update () : Void 
{
    //
}

You can also write a comment on one line:

/** A comment on one line */
public function update () : Void 
{
    //
}

To write even more compact comments, VisDoc supports a shorthand way of writing comments with properties: comments can be listed at the right of the property declarations when they start with /**<. Spaces or tabs can be inserted before the comment to create a neat vertical list:

public var item:String;        /**< Item to be printed.   */ 
public var mc:MovieClip;       /**< Reference to self.    */

Placement of comments
Doc comments are recognized only when placed immediately above the class, interface, property or method declarations (empty lines are allowed). Documentation comments placed in the body of a method are ignored. Only one documentation comment per declaration statement is recognized by VisDoc - if there are multiple comments, only the last one is used.

Comment elements

Doc comments have this structure:
1) Main description
2) Tag section

The main description section begins after the starting /** and continues until the tag section. The description part describes the purpose of the class, property or method in free text.

The first line of the class description is also the summary text of the class. This summary text is copied in some Javadoc overview pages, but this copying is not implemented by VisDoc. The summary text is printed in bold.

According to the Javadoc spec, the first line of member description should be a summary sentence, containing a concise but complete description of the declared entity. This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first block tag.

With VisDoc, the first sentence may also end on a HTML block element (address, blockquote, br, center, del, div, h, hr, ins, li, ol, p, table, td, th, tr, ul).

VisDoc does not write the first sentence to the member summary because I find that this would clutter the page at a location where a quick and clear overview is needed.

A lot of Flash programmers are less familiar with the Javadoc specs and use the (non-existing) @description tag. This tag is supported by VisDoc. If both the description text and the @description tag are used, both texts are concatenated. The second description text starts at a new line.

The tag section starts with the first block tag, which is defined by the first @ character that begins a line (ignoring leading asterisks, white space, and leading separator /**). The text that follows the tag, the argument, can span multiple lines. The order of tags is defined by the Javadoc spec, but is not imposed, so it is up to the writer of the documentation to follow the specs or not. Some tags can be repeated, like the @see tag.

Block tags and inline tags

Block tags appear at the beginning of a line, and plainly start with @, such as @see. Inline tags appear inside text, and are wrapped within curly braces, such as {@link}.

The following example contains the block tag @deprecated and in-line tag {@link}:

/**
@deprecated As of FW 1.1, replaced by {@link #setBounds()}
*/

If you want to start a line with the @ character and not have it be interpreted, use the HTML entity @.

Comments are written in HTML

All generated text is ultimately interpreted by a browser. This means that you should write code that a browser understands. If you want to format text, you must use HTML tags to do this. If you write symbols, escape them.

For example, when you want to use a less-than (<) or greater-than (>) symbol, use the HTML escaped versions < and >. Likewise, the ampersand (&) should be written &.

You often want to include code examples in documentation. You can use either <code></code> or <pre></pre> - these tags are converted by VisDoc depending on the line count of the code text. When the text spans one line, it is wrapped inside <code></code> tags. When the text spans multiple lines, the text is automatically wrapped inside <pre></pre> tags. So if you don't want to be bothered when to use code and when to use pre, always use <code></code>.

Because your average code editor is not a HTML WYSIWYG environment, HTML bugs sneak in easily when writing doc comments. VisDoc is forgiving when it encounters an illegal opening/closing order of pre and code tags: by applying above rule it repairs the bugs.
It tries to do the same when it finds a wrong order of blockquote and code tags - yes that happens too.

Use <hr /> to create separators in long example texts. See @example for an illustration of this.

Tags

VisDoc implements the most important Javadoc tags, and also some new tags that are commonly used or otherwise useful:

@author

Format: @author name-text

Adds an "Author" entry with the specified name-text to the generated docs. A doc comment may contain multiple @author tags. You can specify one name per @author tag or multiple names per tag. In the former case, the Javadoc tool inserts a comma (,) and space between names. In the latter case, the entire text is simply copied to the generated document without being parsed. Therefore, you can use multiple names per line if you want a localized name separator other than comma.
If the author is unknown, you can use "unascribed".

Used in class descriptions.

Example:

/**
@author Arthur Clemens
@author John Doe
*/

Will generate:

• Author: Arthur Clemens, John Doe

{@code}

Format: {@code literal code-text}

Formats the literal code-text in the code font by putting <code></code> tags around the text; {@code abc} is equivalent to <code>{@literal abc}</code>. See also @literal tag.

Example:

/**
Some normal text and {@code some code-formatted text}. 
*/

Will generate:

Some normal text and some code-formatted text.

@deprecated

Format: @deprecated deprecated-text

VisDoc moves the deprecated-text above the description text.

The first sentence of deprecated-text should at least tell the user when the class or member was deprecated and what to use as a replacement. You can use a {@link} tag that points to the replacement API.

Used in class and member descriptions.

Example:

/**
Main description text.
@deprecated As of FW 1.1.
*/

Will generate:

Deprecated As of FW 1.1.

Main description text.

@exception

The @exception tag is a synonym for @throws.

{@inheritDoc}

Insert the inline tag {@inheritDoc} in a method main description or @return, @param or @throws tag comment - the corresponding inherited main description or tag comment is copied into that spot.

If {@inheritDoc} is not used, VisDoc will copy the doc comments from the superclass verbatim. In the example below, the method setX is overridden in a subclass. In the doc comment, the parameter inX is not described, and no explicit {@inheritDoc} is used, so the whole description of this parameter is copied.

VisDoc also copies comments from superclass constructors automatically.

Copied doc comments are provided with a link back to the original text. After each copied element a # sign is used for the link.

Methods that are overridden are automatically given a link to the superclass method under the caption "Overrides". VisDoc also adds links to properties that override superclass properties.

Methods that implement an interface method are given a link to the interface method under the caption "Implemented by".

Example:

/**
Some description here. {@inheritDoc}
@return Some return description here. {@inheritDoc}
*/
public function setX (inX:Number) : Number
{
	//
}

Will generate:

Some description here.

"Exactly," the geographer said. "But I am not an explorer. I haven't a single explorer on my planet. It is not the geographer who goes out to count the towns, the rivers, the mountains, the seas, the oceans, and the deserts. The geographer is much too important to go loafing about. He does not leave his desk. But he receives the explorers in his study. He asks them questions, and he notes down what they recall of their travels. And if the recollections of any one among them seem interesting to him, the geographer orders an inquiry into that explorer's moral character."

#.

Parameters:

inX:

the new x position

#

Returns:

Some return description here.

The retain count

#

Overrides:

Shape.setX

{@link}

Format: {@link package.class#member label}

Inserts an in-line link with visible text label that points to the documentation for the specified package, class or member name of a referenced class.

This tag is very simliar to @see - both require the same references and accept exactly the same syntax for package.class#member and label. The main difference is that {@link} generates an in-line link rather than placing the link in the "See also" section. Also, the {@link} tag begins and ends with curly braces to separate it from the rest of the in-line text. If you need to use "}" inside the label, use the HTML entity notation }.

Used in all doc comments: class, interface, constructor, method and property, including the text portion of any tag (such as @return, @param and @deprecated).

Example:

/**
Main description text, see {@link #otherMethod()}
*/

Will generate:

Main description text, see otherMethod()

Example:

/**
Main description text, see {@link #otherMethod Link to some other method}
*/

Will generate:

Main description text, see Link to some other method

{@literal}

Format: {@literal literal-text}

Denotes literal text. The enclosed text is interpreted as not containing HTML markup or nested javadoc tags. For example, the doc comment text: {@literal a<B>c} displays in the generated HTML page unchanged: a<B>c -- that is, the <B> is not interpreted as bold.

To format literal text in code font, use the {@code} tag.

Example: (note that in a documentation file you can use actual html tag hooks, not &lt;&gt; notation)

/**
{@literal I can use <html> inside here and even 


some newlines}.
*/

Will generate:

I can use <html> inside here and even


some newlines.

{@linkplain}

@linkplain is identical to @link; with Javadoc, @link is rendered in code font and @linkplain in normal font - VisDoc renders all links in normal (plain) font.

@param

Format: parameter-name (:) description

Adds a parameter with the specified parameter-name followed by the specified description to the "Parameters" section.

The parameter-name may be followed by a colon (:), with optional spaces at left and right. If left out, a colon is inserted automatically. Additional spaces can be inserted between the name and description so that the descriptions line up in a block in the code (these are ignored by VisDoc). The description may run over multiple lines.

Used in constructor and method descriptions.

Example:

/**
Main description text.
@param inDrawClip:    the MovieClip to draw into
@param inStartX:      the x position where drawing starts
@param inStartY:      the y position where drawing starts
@param inLineWidth:   (optional) the width of the drawn line in pixels. If not specified, a line width of 1 pixel is assumed.
*/

Will generate:

public function draw (

inDrawClip:MovieClip) : Void

Main description text.

Parameters

inDrawClip :

the MovieClip to draw into

inStartX :

the x position where drawing starts

inStartY :

the y position where drawing starts

inLineWidth:

(optional) the width of the drawn line in pixels. If not specified, a line width of 1 pixel is assumed.

@return

Format: @return description

Adds a "Returns" section with the description text. This text should describe the permissible range of return values.

Used in method descriptions.

Example:

/**
Main description text.
@return True when the passed item is in the list, false when it is not.
*/

Will generate:

Main description text.

Returns

True when the passed item is in the list, false when it is not.

@see

Format: @see reference

Adds a "See also" heading with a link or text entry that points to reference. A doc comment may contain any number of @see tags, which are all grouped under the same heading. The @see tag has three variations; variation 3 is the most common.

Used in all doc comments: class, interface, constructor, method and property.

Variation 1: string @see "string"

Adds a text entry for string. No link is generated. The string is a book or other reference to information not available by URL. VisDoc recognized this from the other variants by looking for a double-quote (") as the first character.

Example:

/**
Main description text.
@see "Colin Moock: Essential ActionScript 2.0, p. 100"
*/

Will generate:

Main description text.

See also

"Colin Moock: Essential ActionScript 2.0, p. 100"

Variation 2: URL @see <a href="URL#value">label</a>

Adds a link as defined by URL#value. The URL#value is a relative or absolute URL. VisDoc recognized this from the other variants by looking for a less-than symbol (<) as the first character.

Example:

/**
Main description text.
@see <a href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html">javadoc specification</a>
*/

Will generate:

Main description text.

See also

Javadoc specification

Variation 3: class or member reference @see package.class#member label

Adds a link, with visible text label, that points to the documentation for the specified name. The label is optional; if omitted, the name appears instead as the visible text, suitably shortened - dependent whether a local method is referenced, or a method in a different class or in a different package.

Syntax:

• To link to a member in the same class, use the #member syntax.
• To link to a member in a different class, use the class#member syntax.
• To link to a member in a different package, use the package.class#member syntax - at least formally. VisDoc detects when a references class is in another package, and substitutes the right syntax for you. See the last 2 entries in the example below, where UtilClass is references in two different ways. The output is the same for both entries.

Example:

/**
Main description text.
@see #draw(drawObject)
@see ReferencedClass#paint()
@see ReferencedClass#draw Draw it
@see com.visiblearea.util.UtilClass#makeLifeEasy()
@see UtilClass#makeLifeEasy()
*/

Will generate:

Main description text.

See also

draw(drawObject)
ReferencedClass.paint()
Draw it
com.visiblearea.util.UtilClass.makeLifeEasy()
com.visiblearea.util.UtilClass.makeLifeEasy()

@since

Format: @since since-text

Adds a "Since" heading with the specified since-text to the generated documentation. This tag means that this change or feature has existed since the software release specified by the since-text. The text has no special internal structure.

Used in all doc comments: class, interface, constructor, method and property.

Example:

/**
Main description text.
@since 1.4
*/

Will generate:

Main description text.

Since

1.4

@throws

Format: @throws class-name description

The @throws and @exception tags are synonyms. Adds a "Throws" subheading to the generated documentation, with the class-name and description text. The class-name is the name of the exception that may be thrown by the method.

Used in constructor and method descriptions.

Example:

/**
Main description text.
@throws VAException if you try to remove an element when none is selected
*/

Will generate:

Main description text.

Throws

VAException if you try to remove an element when none is selected

@version

Format: @version version-text

Adds a "Version" subheading with the specified version-text. This tag is intended to hold the date or the current version number of the software that this code is part of (as opposed to @since, which holds the version number where this code was introduced). The version-text has no special internal structure.

If you use a date text, you must write the date yourself; VisDoc itself does not convert date formats.

Used in class and interface descriptions.

Example:

/**
Main description text.
@version 7 Oct 2004
*/

Will generate:

Main description text.

Version

7 Oct 2004

@private

Format: @private

Explicitly marks property or method as private, even though the method access is public. Private methods can be included in the documentation by setting the option "List private members" in the VisDoc application.

Used in member descriptions.

Example:

/**
Main description text.
@private
*/
function calculate () : Void
{}

Will cause the method to be listed as private.

privatefunction calculate (

) : Void

Main description text.

@description

Format: @description description-text

Identical to the tag-less main description section. If both the description text and the @description tag are used, both texts are concatenated. The second description text starts at a new line.

Use should be discouraged, but can be used in all doc comments: class, interface, constructor, method and property.

Example:

/**
@description Main description text.
*/

Will generate:

Main description text.

Example:

/**
Main description text.
@description Some more description text.
*/

Will generate:

Main description text.
Some more description text.

@example

Format: @example example-text

Adds a "Example" subheading with the specified example-text. A doc comment may contain any number of @example tags, which are all grouped under the same heading.

For instructions about writing code examples, see Comments are written in HTML in this document.

Used in all doc comments: class, interface, constructor, method and property.

Example:

/**
Main description text.
@example
This example shows what methods to implement:
<code>
target.onReady = function ()
{
    font_mng.loadFont("icons");
}
</code>
<hr />
<code>
target.onDone = function ()
{
    font_mng.removeFont("icons");
}
</code>
*/

Will generate:

Main description text.

Example

This example shows what methods to implement:

target.onReady = function ()
{
    font_mng.loadFont("icons");
}

---

target.onDone = function ()
{
    font_mng.removeFont("icons");
}

@returns

Synonym for @return. Supported because this tag is frequently used.

@usage

Synonym for @use.

@use

Format: @use use-text

Will generate a heading with the title "Usage". A doc comment may contain any number of @use tags, which are all grouped under the same heading.

Similar to @example - I find myself using @use more often in a class description to explain the general usage of the class, and @example in member descriptions.

@exclude

Format: @exclude

Excludes (hides) a property, method or class from the documentation.

Used in all doc comments: class, interface, constructor, method and property.

Example:

/**
Main class description text.
@exclude
*/

Will cause this class to be excluded from the documentation. You can use the same method to exclude properties or methods.

@history

Format: @history history-text

To generate a list of changes. Will generate a heading with the title "Version history". A doc comment may contain any number of @history tags, which are all grouped under the same heading. The history-text has no special internal structure. Entries are not sorted automatically.

Used in all doc comments: class, interface, constructor, method and property.

Example:

/**
Main description text.
@history 28 Sep 2004 Optimized KeyListener.
@history 17 Sep 2004 Added double-click to hide window.
*/

Will generate:

Main description text.

Version history

28 Sep 2004 Optimized KeyListener.
17 Sep 2004 Added double-click to hide window.

@img

Format: {@img filename} and {@img url}

Creates an image tag in the documentation. Image files are placed in the folder /img. Alternatively use a full url.

Used in all doc comments: class, interface, constructor, method and property.

Example:

/**
{@img movie_management_glance.png}
*/

Shows image movie_management_glance.png in folder /img.

Example:

/**
{@img http://domain.com/assets/movie_management_glance.png}
*/

Shows an image from a domain.

@implementationNote

Format: @implementationNote implementationNote-text

Point of attention about the implementation, targeted to class developers (as opposed to usageNote that is targeted to class users). Will generate a heading with the title "Implementation note". A doc comment may contain any number of @implementationNote tags, which are all grouped under the same heading. The implementationNote-text has no special internal structure.

Used in all doc comments: class, interface, constructor, method and property.

Example:

/**
Main description text.
@implementationNote A Worker object reference is always added as first argument to the argument list.
*/

Will generate:

Main description text.

Implementation note

A Worker object reference is always added as first argument to the argument list.

@overload

Format: @overload #member

To mark methods that are overloaded by as2lib's Overload class.
Will generate a heading with the title "Overloading". A doc comment may contain any number of @overload tags, which are all grouped under the same heading.

The notation of @overload follows the same rules as @see: each method on one line, with the # method prefix to create a link. For example: @overload #drawByFillAndLineColor.
The method parameters and return type are added automatically to the link.

Used in method descriptions.

Example:

/**
Main description text.
@overload #drawByFillAndLineColor
@overload #drawByFillColor
*/
public function draw() : Void
{}

public function drawByFillAndLineColor(fillColor:Color, lineColor:Color) : Void
{}

public function drawByFillColor(fillColor:Color) : Void
{}

Will generate:

Main description text.

Overloading

drawByFillAndLineColor (fillColor:Color, lineColor:Color) : Void
drawByFillColor (fillColor:Color) : Void

@sends

Format 1: @sends method-text # comment-text
Format 2: @sends event-classname#type-name comment-text

To document messages that are broadcast to listeners. Will generate a heading with the title "Events broadcast to listeners". A doc comment may contain any number of @sends tags, which are all grouped under the same heading.

The sends parameter text is either:

1. the event handler (name, parameters, returnvalue) that is implemented by the listener. Used for BroadcasterMX. See example 1 below.
2. a reference to an event class with the event type. Used for EventDispatcher. See example 2 below.

All @sends entries are duplicated to the class description, to provide a quick overview of messages that are sent by the class.

Used in method descriptions.

Example 1, BroadcasterMX syntax:

In this example the following event handler is implemented by the listener:

public function onLoadProgress(name:String, total:Number, loaded:Number, this:Loader) : Void
{}

/**
Main description text.
@sends onLoadProgress(name:String, total:Number, loaded:Number, this:Loader):Void # - during loading
*/

Will generate:

Main description text.

Events broadcast to listeners

onLoadProgress (name:String, total:Number, loaded:Number, this:Loader) : Void - during loading

Example 2, EventDispatcher syntax:

In this example an event object of class SomeEvent is sent, with the type set to "onChangeEvent": dispatchEvent(new SomeEvent(this, "onChangeFocus"));

/**
Main description text.
@sends SomeEvent#onChangeFocus - when a change of focus is detected
*/

Will generate:

Main description text.

Events broadcast to listeners

SomeEvent with type: onChangeFocus - when a change of focus is detected

You can use this syntax as well for generic value objects. The event object is not given here, and the phrase "Object with type:" is automatically inserted:

/**
Main description text.
@sends #click
*/
public function someMethod () : Void 
{
	dispatchEvent({type:"click"});
}

Will generate:

Main description text.

Events broadcast to listeners

Object with type: click

@todo

Format: @todo todo-text

To generate a list of TODO texts. Will generate a heading with the title "To do". A doc comment may contain any number of @todo tags, which are all grouped under the same heading. The todo-text has no special internal structure.

Used in all doc comments: class, interface, constructor, method and property.

Example:

/**
Main description text.
@todo 1. International date format (order of date parts)
@todo 2. UTC date format
*/

Will generate:

Main description text.

To do

1. International date format (order of date parts)
2. UTC date format

@usageNote

Format: @usageNote usageNote-text

Point of attention when using a class or class member, targeted to class users (as opposed to implementationNote that is targeted to class developers). Will generate a heading with the title "Usage note". A doc comment may contain any number of @usageNote tags, which are all grouped under the same heading. The usageNote-text has no special internal structure.

Used in all doc comments: class, interface, constructor, method and property.

Example:

/**
Main description text.
@usageNote Be careful not to attach an object that does not listen to removeListener,
like common movieclips, or the listener will persist and keep on sending messages.
*/

Will generate:

Main description text.

Usage note

Be careful not to attach an object that does not listen to removeListener, like common movieclips, or the listener will persist and keep on sending messages.

Other useful information

• VisDoc only parses files with the extension .as or .java and that have a valid class declaration. That excludes ActionScript 1.0 files.
• If VisDoc encounters multiple files with the same classpath, only the most recent file is used.