xjavadoc

Class XDoc

public final class XDoc extends Object implements XTagListener

Represents documentation

Author: Aslak Hellesxy

UNKNOWN: 20. mars 2003

Field Summary
static StringEMPTY_COMMENT
Default comment
static intinstanceCount
static StringNEWLINE
Platform specific NEWLINE.
String_commentText
description of program element
boolean_dirty
Set_docListeners
String_firstSentence
first sentence of comment text
Token_javadocToken
Token (which is linked in the AST) that holds the string representation of the doc.
XProgramElement_owner
XTagFactory_tagFactory
Map_tagMap
Maps tag name to List.
List_tags
Contains all the tags in the doc, in order of occurrence.
Constructor Summary
XDoc(Token javadocToken, XProgramElement owner, XTagFactory tagFactory)
Describe what the XDoc constructor does
Method Summary
voidaddDocListener(XDocListener docListener)
Add doc listener interested in changes.
XTagaddTag(String tagName, String text)
Add a tag to the doc item.
XTagaddTag_Impl(String tagName, String text, int lineNumber)
Creates and adds a tag
StringBufferappendWhiteSpaces(StringBuffer sb)
Add some white space to the string being built up in toString().
static Stringdotted(String tagName)
Convert a tag name from the old colon-separated form to the new preferred dot-separated form.
voidensureTagMapInitialised()
voidfireDocChanged()
fire docChange event
ListgetAllSuperDocs()
Returns the doc in all the superclasses.
StringgetCommentText()
return description of program element
StringgetFirstSentence()
Return the first sentence of the text of the comment for this doc item.
XProgramElementgetOwner()
Gets the Owner attribute of the XDoc object
XDocgetSuperDoc()
Returns the doc in the superclass.
XTaggetTag(String tagName)
Get the first tag of name tagName from this doc.
XTaggetTag(String tagName, boolean superclasses)
Get the first tag of name tagName.
StringgetTagAttributeValue(String tagName, String attributeName)
Returns the tag attribute value.
StringgetTagAttributeValue(String tagName, String attributeName, boolean superclasses)
Returns the tag attribute value.
ListgetTags(String tagName)
Returns all the tags in this doc with the specified tagName (not superclasses).
ListgetTags(String tagName, boolean superclasses)
Returns all the tags with the specified tagName.
ListgetTags()
Returns all the tags in this doc (not superclasses).
ListgetTags(boolean superclasses)
Returns all the tags.
booleanhasTag(String tagName)
Returns true if the tag exists.
booleanhasTag(String tagName, boolean superclasses)
Returns true if the tag exists.
voidparse()
Parse token into comments, tags and tag attributes.
voidremoveDocListener(XDocListener docListener)
remove doc listener
booleanremoveTag(XTag tag)
Removes tag.
voidsetCommentText(String commentText)
Set the text of the comment for this doc item.
voidtagChanged(XTagEvent event)
receive change notification from xtag
static StringtokenizeAndTrim(String s)
StringtoString()
Returns a String representation of this doc.
XTagupdateTagValue(String tagName, String attributeName, String attributeValue, int tagIndex)
Utility method to set the value of a tag attribute.
voidupdateToken()
update token

Field Detail

EMPTY_COMMENT

private static final String EMPTY_COMMENT
Default comment

instanceCount

public static int instanceCount

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.

Constructor Detail

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 Detail

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

Throws: TagValidationException if validation is activated (in XTagFactory) and tagName is not among the registered tags.

addTag_Impl

private XTag addTag_Impl(String tagName, String text, int lineNumber)
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(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()
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(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()
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

Parameters: event

tokenizeAndTrim

private static final String tokenizeAndTrim(String s)

toString

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

Returns: a String representation of this doc.

updateTagValue

public XTag updateTagValue(String tagName, String attributeName, String attributeValue, int tagIndex)
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 tagIndex The index of the tag to update, in case there are several tags with the same name. attributeName The attribute name attributeValue The new attribute value

Returns: the updated tag

Throws: XJavaDocException

updateToken

public void updateToken()
update token