xjavadoc
Class XDoc

java.lang.Object
  extended byxjavadoc.XDoc
All Implemented Interfaces:
java.util.EventListener, XTagListener

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

Represents documentation

Author:
Aslak Hellesøy

Field Summary
private  java.lang.String _commentText
          description of program element
private  boolean _dirty
           
private  java.util.Set _docListeners
           
private  java.lang.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  java.util.Map _tagMap
          Maps tag name to List.
private  java.util.List _tags
          Contains all the tags in the doc, in order of occurrance
private static java.lang.String EMPTY_COMMENT
          Default comment
static int instanceCount
           
private static java.lang.String NEWLINE
          Platform specific NEWLINE.
 
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 chages
private  XTag addTag_Impl(java.lang.String tagName, java.lang.String text, int lineNumber)
          Creates and adds a tag
 XTag addTag(java.lang.String tagName, java.lang.String text)
          Describe the method
private  java.lang.StringBuffer appendWhiteSpaces(java.lang.StringBuffer sb)
          Describe the method
static java.lang.String dotted(java.lang.String tagName)
           
private  void ensureTagMapInitialised()
           
private  void fireDocChanged()
          fire docChange event
private  java.util.List getAllSuperDocs()
           
 java.lang.String getCommentText()
          return description of program element
 java.lang.String getFirstSentence()
          Describe what the method does
 XProgramElement getOwner()
          Gets the Owner attribute of the XDoc object
private  XDoc getSuperDoc()
          Returns the doc in the superclass.
 XTag getTag(java.lang.String tagName)
          Describe what the method does
 XTag getTag(java.lang.String tagName, boolean superclasses)
          Get the first tag of name tagName
 java.lang.String getTagAttributeValue(java.lang.String tagName, java.lang.String attributeName)
          Returns the tag attribute value.
 java.lang.String getTagAttributeValue(java.lang.String tagName, java.lang.String attributeName, boolean superclasses)
          Returns the tag attribute value.
 java.util.List getTags()
          Returns all the tags in this doc (not superclasses).
 java.util.List getTags(boolean superclasses)
          Returns all the tags with the specified tagName.
 java.util.List getTags(java.lang.String tagName)
          Returns all the tags in this doc with the specified tagName (not superclasses).
 java.util.List getTags(java.lang.String tagName, boolean superclasses)
          Returns all the tags with the specified tagName.
 boolean hasTag(java.lang.String tagName)
          Returns true if the tag exists.
 boolean hasTag(java.lang.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(java.lang.String commentText)
          set comment text
 void tagChanged(XTagEvent event)
          receive change notification from xtag
private static java.lang.String tokenizeAndTrim(java.lang.String s)
           
 java.lang.String toString()
          Returns a String representation of this doc.
 XTag updateTagValue(java.lang.String tagName, java.lang.String attributeName, java.lang.String attributeValue, int tagIndex)
          Utility method to set the value of a tag attribute.
 void updateToken()
          update token
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

instanceCount

public static int instanceCount

NEWLINE

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


EMPTY_COMMENT

private static final java.lang.String EMPTY_COMMENT
Default comment

See Also:
Constant Field Values

_tagMap

private java.util.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


_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

_tags

private java.util.List _tags
Contains all the tags in the doc, in order of occurrance


_commentText

private java.lang.String _commentText
description of program element


_firstSentence

private java.lang.String _firstSentence
first sentence of comment text


_dirty

private boolean _dirty

_docListeners

private java.util.Set _docListeners

_tagFactory

private final XTagFactory _tagFactory
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
Method Detail

dotted

public static java.lang.String dotted(java.lang.String tagName)

tokenizeAndTrim

private static final java.lang.String tokenizeAndTrim(java.lang.String s)

getOwner

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

Returns:
The Owner value

getTags

public java.util.List getTags(java.lang.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 java.util.List getTags(java.lang.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 java.util.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 java.util.List getTags(boolean superclasses)
Returns all the tags with the specified tagName. If No tags are found, an empty Collection is returned.

Parameters:
superclasses - if this is true, return tags from superclasses too.
Returns:
A Collection of XTag

getTag

public XTag getTag(java.lang.String tagName)
Describe what the method does

Parameters:
tagName - Describe what the parameter does
Returns:
Describe the return value

getTag

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

Parameters:
tagName - the name of the tag to get.
superclasses - Describe what the parameter does
Returns:
the first XTag with name equal to tagName

getTagAttributeValue

public java.lang.String getTagAttributeValue(java.lang.String tagName,
                                             java.lang.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 java.lang.String getTagAttributeValue(java.lang.String tagName,
                                             java.lang.String attributeName,
                                             boolean superclasses)
Returns the tag attribute value. If superclasses is true, the first occurrance 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.

getCommentText

public java.lang.String getCommentText()
return description of program element

Returns:
description of program element

getFirstSentence

public java.lang.String getFirstSentence()
Describe what the method does

Returns:
Describe the return value

setCommentText

public void setCommentText(java.lang.String commentText)
set comment text

Parameters:
commentText - The new CommentText value

hasTag

public boolean hasTag(java.lang.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 is the tag exists

hasTag

public boolean hasTag(java.lang.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 is the tag exists

updateTagValue

public XTag updateTagValue(java.lang.String tagName,
                           java.lang.String attributeName,
                           java.lang.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
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

addDocListener

public void addDocListener(XDocListener docListener)
add doc listener interested in chages

Parameters:
docListener - doc listener to register

removeDocListener

public void removeDocListener(XDocListener docListener)
remove doc listener

Parameters:
docListener -

toString

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

Returns:
a String representation of this doc.

updateToken

public void updateToken()
update token


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

addTag

public XTag addTag(java.lang.String tagName,
                   java.lang.String text)
Describe the method

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.

tagChanged

public void tagChanged(XTagEvent event)
receive change notification from xtag

Specified by:
tagChanged in interface XTagListener
Parameters:
event -

getSuperDoc

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

Returns:
Describe the return value

getAllSuperDocs

private java.util.List getAllSuperDocs()

ensureTagMapInitialised

private final void ensureTagMapInitialised()

addTag_Impl

private XTag addTag_Impl(java.lang.String tagName,
                         java.lang.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

fireDocChanged

private void fireDocChanged()
fire docChange event


appendWhiteSpaces

private java.lang.StringBuffer appendWhiteSpaces(java.lang.StringBuffer sb)
Describe the method

Parameters:
sb - Describe the method parameter
Returns:
Describe the return value

parse

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

Throws:
TagValidationException