Examples of DocComment

sun.com/j2se/javadoc/writingdoccomments/#format">How to Write Doc Comments for the Javadoc Tool (bearing in mind that some of the tags defined for Java docuemtation may not be processed by ActionScript tools).

Automatic Comment Formatting

Documentation comments are formatted with indentation to match the surrounding source code, and a column of asterisks ('*') along the left hand side of the comment block. Both of these foratting tasks are carried out for you automatically by metaas. So for example if you create a two-line description as follows,

docComment.setDescriptionString("Great\n"+ "stuff.");

The generated comment in the source code would have the appropriate indentation, and asterisk characters added to produce a nicely formatted documentation comment,

/ * Great * stuff. */

Conversely, when retreving the descriptive text from the comment, this extra formatting is removed before you see it,

docComment.getDescriptionString();  => " Great\n stuff."

HTML Formatting

It's common to include HTML tags in documentation comments to provide some additional formatting in the generated documentation. metaas doesn't currently check the formatting of any HTML, but future versions may require well-formed XHTML.

Inline Tags

Documentation tools can process special 'inline' documetation tags with in documentation-comment descriptions, for instance {@link com.example.ThatClass}. Future versions of metaas may expose information about such tags.

Tagged Paragraphs

Tagged paragraphs are used in JavaDoc-style comments to provide additional, structured information to tools generating documentation from the source code. A typical example would be the @see entries in a piece of API documentation, that might be skipped by a documentation tool when producing overview documatation, but will be included in a detailed description of the particular API area.

To add a @see tagged-paragraph to a comment, use {@link #addParaTag(String,String)}. e.g.

docComment.addParaTag("see", "com.example.SomeClass")

The resulting comment would look something like,

/ * @see com.example */

The 'tag' of a tagged paragraph must always start at the beginning of a line. If @see appears in the middle of a line of text, if is taken to be part of the description, an will not be returned by {@link #findTags(String)} (for example).

To prevent mangled comments being generated by accident, it is an error to include content that might be interpreted as a tagged-paragraph,

docComment.setDescription("Funny description.\n" "@dave: hahaha");

will raise a SyntaxException,

uk.co.badgersinfoil.metaas.SyntaxException: trailing content after description: "@dave"

Shortcuts

Other elements in the metaas API provide shorcuts for accessing specific parts of the documentation-comment structure (e.g. creating or updating specific tagged-paragraphs),

{@link ASArg#getDescriptionString()}, {@link ASArg#setDescription(String)} for easy access to@param tags in a method comment
{@link ASMethod#getReturnDescriptionString()}, {@link ASMethod#setReturnDescription(String)}.

@see Documentable