|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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).
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."
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.
{@link com.example.ThatClass}
. Future versions of
metaas may expose information about such tags.
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"
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),
ASArg.getDescriptionString()
,
ASArg.setDescription(String)
for easy access to
@param tags in a method commentASMethod.getReturnDescriptionString()
,
ASMethod.setReturnDescription(String)
.
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 |
---|
java.lang.String getDescriptionString()
/** * Test stuff * @return something */This method would return a String something like "Test stuff"
void setDescriptionString(java.lang.String description)
SyntaxException
- if the given text contains an end-of-comment
marker, or a tagged-paragraphsetDescriptionString(String)
java.util.Iterator findTags(java.lang.String name)
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.
name
- The paragraph tag name, not including the leading '@'
symbol.DocTag findFirstTag(java.lang.String name)
name
- The paragraph tag name, not including the leading '@'
symbol.void delete(DocTag tag)
void addParaTag(java.lang.String name, java.lang.String body)
SyntaxException
- if the given text contains an end-of-comment
marker, or a tagged-paragraph
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |