Addition of a special form of comment used to combine documentation directly into the code from which web pages can be created to describe the code or API.

Jeff Walker (language designer)

jwalker@cs.oberlin.edu

Java has demonstrated the great usefulness of documentation of this kind.

Document comments are block comments with an extra asterisk at the beginning, so they begin '/**'. This is followed by multiple lines beginning with aligned asterisks until the comment termination is found.

Text in these blocks describes the object or expression following the comment. A documentation comment may appear before any kind of object to describe that object. Documentation comments may also appear in object bodies in some cases. Special tags are introduced by the '@' sign. These should be put on individual lines after the textual comments.

@author

The author (generally of classes), use unascribed if the author is unknown. Multiple author tags may be included if their are multiple authors.

@version

Used on classes to specify an arbitrary version for the class.

@param

The @param can be used to describe parameters to methods and other patterns. They should be listed in the order given. The tag should be followed by the param name then by a description of the tag.

@return

Used to provide a comment of the return type of a pattern. Omit if the type is void or self.

@since

Used to describe what version of a product or API this object or method first appeared in.

@throws

Can be used to describe an exception which a method throws.

@link( )

Used to include a link to the documentation for another object. List the name of the object to link to in the parameter to the link tag. To provide a different name for the link add a second argument of the name as you would like it to appear. (May require different syntax to allow embedding).

@see

Similar to the link tag but used on its own line after other tags.

@remove

May be used as the first item in a documentation tag followed by a date and description of why something was removed. The removed content then follows in the comment. Removed code may be expressions in a method or an entire object. Since comments may be nested removed code can contain documentation comments about the removed code. Removed objects may be listed in the generated documentation. Removed expressions will generally not be shown. This can be used to preserve old versions of code to remind programmers of previous code states.

Optional other suggestions. Allow documentation comments of the form '//*' which could contain single line tags. Example @break used to put break points or conditional break points in. Also @pre and @post to specify pre and post conditions.

jwalker@cs.oberlin.edu