xjavadoc

Class XDoc

Implemented Interfaces:
EventListener, XTagListener

public final class XDoc
extends java.lang.Object
implements XTagListener

Represents documentation

Author:
Aslak Helles?y

Field Summary

private static String
EMPTY_COMMENT
Default comment
private static String
NEWLINE
Platform specific NEWLINE.
private String
_commentText
description of program element
private boolean
_dirty
private Set
_docListeners
private String
_firstSentence
first sentence of comment text
private Token
_javadocToken
Token (which is linked in the AST) that holds the string representation of the doc.
private XProgramElement
_owner
private XTagFactory
_tagFactory
private Map
_tagMap
Maps tag name to List.
private List
_tags
Contains all the tags in the doc, in order of occurrence.
static int
instanceCount

Constructor Summary

XDoc(Token javadocToken, XProgramElement owner, XTagFactory tagFactory)
Describe what the XDoc constructor does

Method Summary

void
addDocListener(XDocListener docListener)
Add doc listener interested in changes.
XTag
addTag(String tagName, String text)
Add a tag to the doc item.
private XTag
addTag_Impl(String tagName, String text, int lineNumber)
Creates and adds a tag
private StringBuffer
appendWhiteSpaces(StringBuffer sb)
Add some white space to the string being built up in toString().
static String
dotted(String tagName)
Convert a tag name from the old colon-separated form to the new preferred dot-separated form.
private void
ensureTagMapInitialised()
private void
fireDocChanged()
fire docChange event
private List
getAllSuperDocs()
Returns the doc in all the superclasses.
String
getCommentText()
return description of program element
String
getFirstSentence()
Return the first sentence of the text of the comment for this doc item.
XProgramElement
getOwner()
Gets the Owner attribute of the XDoc object
private XDoc
getSuperDoc()
Returns the doc in the superclass.
XTag
getTag(String tagName)
Get the first tag of name tagName from this doc.
XTag
getTag(String tagName, boolean superclasses)
Get the first tag of name tagName.
String
getTagAttributeValue(String tagName, String attributeName)
Returns the tag attribute value.
String
getTagAttributeValue(String tagName, String attributeName, boolean superclasses)
Returns the tag attribute value.
List
getTags()
Returns all the tags in this doc (not superclasses).
List
getTags(String tagName)
Returns all the tags in this doc with the specified tagName (not superclasses).
List
getTags(String tagName, boolean superclasses)
Returns all the tags with the specified tagName.
List
getTags(boolean superclasses)
Returns all the tags.
boolean
hasTag(String tagName)
Returns true if the tag exists.
boolean
hasTag(String tagName, boolean superclasses)
Returns true if the tag exists.
private void
parse()
Parse token into comments, tags and tag attributes.
void
removeDocListener(XDocListener docListener)
remove doc listener
boolean
removeTag(XTag tag)
Removes tag.
void
setCommentText(String commentText)
Set the text of the comment for this doc item.
void
tagChanged(XTagEvent event)
receive change notification from xtag
String
toString()
Returns a String representation of this doc.
private static String
tokenizeAndTrim(String s)
XTag
updateTagValue(String tagName, String attributeName, String attributeValue, int tagIndex)
Utility method to set the value of a tag attribute.
void
updateToken()
update token

Field Details

EMPTY_COMMENT

private static final String EMPTY_COMMENT
Default comment


NEWLINE

private static final String NEWLINE
Platform specific NEWLINE. Javadoc will use this as new line.


_commentText

private String _commentText
description of program element


_dirty

private boolean _dirty


_docListeners

private Set _docListeners


_firstSentence

private String _firstSentence
first sentence of comment text


_javadocToken

private Token _javadocToken
Token (which is linked in the AST) that holds the string representation of the doc. Needed for printing out the class.


_owner

private XProgramElement _owner


_tagFactory

private final XTagFactory _tagFactory


_tagMap

private Map _tagMap
Maps tag name to List. The Collection contains XTag instances whose name = name (the map key). The tags in the Lists are ordered by occurrance


_tags

private List _tags
Contains all the tags in the doc, in order of occurrence.


instanceCount

public static int instanceCount

Constructor Details

XDoc

public XDoc(Token javadocToken,
            XProgramElement owner,
            XTagFactory tagFactory)
Describe what the XDoc constructor does

Parameters:
javadocToken - Describe what the parameter does
owner - Describe what the parameter does
tagFactory - Describe what the parameter does

Method Details

addDocListener

public void addDocListener(XDocListener docListener)
Add doc listener interested in changes.

Parameters:
docListener - doc listener to register


addTag

public XTag addTag(String tagName,
                   String text)
Add a tag to the doc item.

Parameters:
tagName - The name of the tag to add
text - The value of the tag

Returns:
The created XTag


addTag_Impl

private XTag addTag_Impl(String tagName,
                         String text,
                         int lineNumber)
            throws TagValidationException
Creates and adds a tag

Parameters:
tagName - The name of the tag (without the 'at')
text - The raw content of the tag
lineNumber - The feature to be added to the Tag_Impl attribute

Returns:
An instance of XTag, created by the current XTagFactory

Throws:
TagValidationException -


appendWhiteSpaces

private StringBuffer appendWhiteSpaces(StringBuffer sb)
Add some white space to the string being built up in toString().

Parameters:
sb - StringBuffer that the text is being built in

Returns:
the StringBuffer


dotted

public static String dotted(String tagName)
Convert a tag name from the old colon-separated form to the new preferred dot-separated form.

Parameters:
tagName - The name of the tag

Returns:
Preferred form of the tag


ensureTagMapInitialised

private final void ensureTagMapInitialised()


fireDocChanged

private void fireDocChanged()
fire docChange event


getAllSuperDocs

private List getAllSuperDocs()
Returns the doc in all the superclasses. If the super element is null, or not from source, an empty list is returned.

Returns:
A List of XDoc


getCommentText

public String getCommentText()
return description of program element

Returns:
description of program element


getFirstSentence

public String getFirstSentence()
Return the first sentence of the text of the comment for this doc item.

Returns:
First sentence


getOwner

public XProgramElement getOwner()
Gets the Owner attribute of the XDoc object

Returns:
The Owner value


getSuperDoc

private XDoc getSuperDoc()
Returns the doc in the superclass. If the super element is null, or not from source, null is returned.

Returns:
the superclass' doc


getTag

public XTag getTag(String tagName)
Get the first tag of name tagName from this doc. Superclasses are not searched.

Parameters:
tagName - the name of the tag

Returns:
the tag


getTag

public XTag getTag(String tagName,
                   boolean superclasses)
Get the first tag of name tagName.

Parameters:
tagName - the name of the tag to get (without the 'at')
superclasses - if this is true, return tags from superclasses too.

Returns:
the first XTag with name equal to tagName


getTagAttributeValue

public String getTagAttributeValue(String tagName,
                                   String attributeName)
Returns the tag attribute value. Does not look in superclasses. If nothing is found, null is returned.

Parameters:
tagName - The name of the tag to look for (without the 'at')
attributeName - The name of the attribute to look for within the tag.

Returns:
The value of the tag attribute.


getTagAttributeValue

public String getTagAttributeValue(String tagName,
                                   String attributeName,
                                   boolean superclasses)
Returns the tag attribute value. If superclasses is true, the first occurrence is returned when walking up the class hierarchy. If nothing is found, null is returned.

Parameters:
tagName - The name of the tag to look for (without the 'at')
attributeName - The name of the attribute to look for within the tag.
superclasses - Set it to true to look in superclasses too.

Returns:
The value of the tag attribute.


getTags

public List getTags()
Returns all the tags in this doc (not superclasses). If No tags are found, an empty Collection is returned.

Returns:
A Collection of XTag


getTags

public List getTags(String tagName)
Returns all the tags in this doc with the specified tagName (not superclasses). If No tags are found, an empty Collection is returned.

Parameters:
tagName - the name of the tags to return (without the 'at')

Returns:
A Collection of XTag


getTags

public List getTags(String tagName,
                    boolean superclasses)
Returns all the tags with the specified tagName. If No tags are found, an empty Collection is returned.

Parameters:
tagName - the name of the tags to return (without the 'at')
superclasses - if this is true, return tags from superclasses too.

Returns:
A Collection of XTag


getTags

public List getTags(boolean superclasses)
Returns all the tags. If no tags are found, an empty List is returned.

Parameters:
superclasses - if this is true, return tags from superclasses too.

Returns:
A List of XTag


hasTag

public boolean hasTag(String tagName)
Returns true if the tag exists. Does not look in superclasses.

Parameters:
tagName - The name of the tag to look for (without the 'at')

Returns:
true if the tag exists


hasTag

public boolean hasTag(String tagName,
                      boolean superclasses)
Returns true if the tag exists.

Parameters:
tagName - The name of the tag to look for (without the 'at')
superclasses - If true, look in superclasses too.

Returns:
true if the tag exists


parse

private void parse()
            throws TagValidationException
Parse token into comments, tags and tag attributes. We remove excess spaces.

Throws:
TagValidationException -


removeDocListener

public void removeDocListener(XDocListener docListener)
remove doc listener

Parameters:
docListener -


removeTag

public boolean removeTag(XTag tag)
Removes tag. Note that XTag objects are compared by identity.

Parameters:
tag - tag to be removed

Returns:
true if it was removed


setCommentText

public void setCommentText(String commentText)
Set the text of the comment for this doc item.

Parameters:
commentText - The new comment text


tagChanged

public void tagChanged(XTagEvent event)
receive change notification from xtag
Specified by:
tagChanged in interface XTagListener

Parameters:
event -


toString

public String toString()
Returns a String representation of this doc.

Returns:
a String representation of this doc.


tokenizeAndTrim

private static final String tokenizeAndTrim(String s)


updateTagValue

public XTag updateTagValue(String tagName,
                           String attributeName,
                           String attributeValue,
                           int tagIndex)
            throws XJavaDocException
Utility method to set the value of a tag attribute. If the tag doesn't exist, it is created. If the attribute doesn't exist it is created. If the tag attribute exists, it is updated.

Parameters:
tagName - The new name of the tag to update (without the
attributeName - The attribute name
attributeValue - The new attribute value
tagIndex - The index of the tag to update, in case there are several tags with the same name.

Returns:
the updated tag

Throws:
XJavaDocException -


updateToken

public void updateToken()
update token