uk.co.badgersinfoil.metaas.dom
Interface DocComment


public interface DocComment

Allows manipulation of any 'documentation comment' attached to an ActionScript API element. You can create a DocComment object for anything implementing the Documentable interface, even if the element in question has no documentation comment attached right now. Methods of this interface will create a doc-comment in the source code as required.

For a description of the format of documentation comments as they appear in the source code, see 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 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 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),

See Also:
Documentable

Method Summary
 void addParaTag(java.lang.String name, java.lang.String body)
          Adds a tagged paragraph with the given tag-name and body text to the end of this documentation comment.
 void delete(DocTag tag)
          Removes the given tag from this comment.
 DocTag findFirstTag(java.lang.String name)
          Returns the first tagged paragraph in this documentation comment that has a tag name matching the name given.
 java.util.Iterator findTags(java.lang.String name)
          Returns an iterator over the list of DocTag elements of this comment that have a tag name matching the given name.
 java.lang.String getDescriptionString()
          Returns the description from this comment.
 void setDescriptionString(java.lang.String description)
          Defines the 'description' part of this documentation comment.
 

Method Detail

getDescriptionString

java.lang.String getDescriptionString()
Returns the description from this comment. The description is the text up until the first tagged paragraph. For instance, given the comment,
/**
 * Test stuff
 * @return something
 */
This method would return a String something like "Test stuff"


setDescriptionString

void setDescriptionString(java.lang.String description)
Defines the 'description' part of this documentation comment.

Throws:
SyntaxException - if the given text contains an end-of-comment marker, or a tagged-paragraph
See Also:
setDescriptionString(String)

findTags

java.util.Iterator findTags(java.lang.String name)
Returns an iterator over the list of DocTag elements of this comment that have a tag name matching the given name. To find all the @see tags in the comment, you could use code like,
Iterator i = docComment.findTags("see");

If there is currently no comment in the source code corresponding to this DocComment object, an Iterator will be returned that simply produces no elements.

Parameters:
name - The paragraph tag name, not including the leading '@' symbol.

findFirstTag

DocTag findFirstTag(java.lang.String name)
Returns the first tagged paragraph in this documentation comment that has a tag name matching the name given.

Parameters:
name - The paragraph tag name, not including the leading '@' symbol.

delete

void delete(DocTag tag)
Removes the given tag from this comment.


addParaTag

void addParaTag(java.lang.String name,
                java.lang.String body)
Adds a tagged paragraph with the given tag-name and body text to the end of this documentation comment. The name should be given without the '@'-prefix, and this will be added by metaas.

Throws:
SyntaxException - if the given text contains an end-of-comment marker, or a tagged-paragraph


Copyright © 2006-2007 David Holroyd. All Rights Reserved.