jdiff
Class RootDocToXML

java.lang.Object
  extended by jdiff.RootDocToXML

public class RootDocToXML
extends java.lang.Object

Converts a Javadoc RootDoc object into a representation in an XML file. See the file LICENSE.txt for copyright details.


Field Summary
static java.lang.String apiIdentifier
          The identifier of the API being written out in XML, e.g.
static java.lang.String baseURI
          The base URI for locating necessary DTDs and Schemas.
static java.lang.String classVisibilityLevel
          Do not display a class with a lower level of visibility than this.
static boolean doExclude
          If set, exclude program elements marked with whatever the exclude tag is specified as, e.g.
static java.lang.String excludeTag
          Exclude program elements marked with this String, e.g.
static java.lang.String memberVisibilityLevel
          Do not display a member with a lower level of visibility than this.
static java.lang.String outputDirectory
          The name of the directory where the XML representing the API will be stored.
static java.lang.String outputFileName
          The name of the file where the XML representing the API will be stored.
static boolean saveAllDocs
          If set, then save the entire contents of a doc block comment in the API file.
 
Constructor Summary
RootDocToXML()
          Default constructor.
 
Method Summary
 void addCommonModifiers(ProgramElementDoc ped, int indent)
          Add qualifiers for the program element as attributes.
 void addDocumentation(ProgramElementDoc ped, int indent)
          Add at least the first sentence from a doc block to the API.
 void addPkgDocumentation(RootDoc root, PackageDoc pd, int indent)
          Add at least the first sentence from a doc block for a package to the API.
 void addSourcePosition(ProgramElementDoc ped, int indent)
          Insert the source code details, if available.
 void emitType(com.sun.javadoc.Type type)
          Emit the type name.
 void emitXMLFooter()
          Emit the XML footer.
 void emitXMLHeader()
          Emit the XML header.
static int endOfFirstSentence(java.lang.String text)
          Find the index of the end of the first sentence in the given text, when writing out to an XML file.
static int endOfFirstSentence(java.lang.String text, boolean writingToXML)
          Find the index of the end of the first sentence in the given text.
 boolean inRange(int val, int min, int max)
          Return true if val is in the range [min|max], inclusive.
 void logOptions()
          Write the options which were used to generate this XML file out as XML comments.
static int minIndex(int i, int j)
          Return the minimum of two indexes if > -1, and return -1 only if both indexes = -1.
 void processClasses(ClassDoc[] cd, java.lang.String pkgName)
          Process classes and interfaces.
 void processConstructors(ConstructorDoc[] ct)
          Process the constructors in the class.
 void processExceptions(ClassDoc[] cd)
          Process all exceptions thrown by a constructor or method.
 void processFields(FieldDoc[] fd)
          Process the fields in the class.
 void processInterfaces(java.lang.reflect.Type[] ifaces)
          Process the interfaces implemented by the class.
 void processMethods(ClassDoc cd, MethodDoc[] md)
          Process the methods in the class.
 void processPackages(RootDoc root)
          Process each package and the classes/interfaces within it.
 boolean shownElement(Doc doc, java.lang.String visLevel)
          Determine if the program element is shown, according to the given level of visibility.
 java.lang.String stripNonPrintingChars(java.lang.String s, Doc doc)
          Strip out non-printing characters, replacing them with a character which will not change where the end of the first sentence is found.
static boolean writeXML(RootDoc root)
          Write the XML representation of the API to a file.
static void writeXSD()
          Write the XML Schema file used for validation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

outputFileName

public static java.lang.String outputFileName
The name of the file where the XML representing the API will be stored.


apiIdentifier

public static java.lang.String apiIdentifier
The identifier of the API being written out in XML, e.g. "SuperProduct 1.3".


outputDirectory

public static java.lang.String outputDirectory
The name of the directory where the XML representing the API will be stored.


classVisibilityLevel

public static java.lang.String classVisibilityLevel
Do not display a class with a lower level of visibility than this. Default is to display all public and protected classes.


memberVisibilityLevel

public static java.lang.String memberVisibilityLevel
Do not display a member with a lower level of visibility than this. Default is to display all public and protected members (constructors, methods, fields).


saveAllDocs

public static boolean saveAllDocs
If set, then save the entire contents of a doc block comment in the API file. If not set, then just save the first sentence. Default is that this is set.


doExclude

public static boolean doExclude
If set, exclude program elements marked with whatever the exclude tag is specified as, e.g. "@exclude".


excludeTag

public static java.lang.String excludeTag
Exclude program elements marked with this String, e.g. "@exclude".


baseURI

public static java.lang.String baseURI
The base URI for locating necessary DTDs and Schemas. By default, this is "http://www.w3.org". A typical value to use local copies of DTD files might be "file:///C:/jdiff/lib"

Constructor Detail

RootDocToXML

public RootDocToXML()
Default constructor.

Method Detail

writeXML

public static boolean writeXML(RootDoc root)
Write the XML representation of the API to a file.

Parameters:
root - the RootDoc object passed by Javadoc
Returns:
true if no problems encountered

writeXSD

public static void writeXSD()
Write the XML Schema file used for validation.


logOptions

public void logOptions()
Write the options which were used to generate this XML file out as XML comments.


processPackages

public void processPackages(RootDoc root)
Process each package and the classes/interfaces within it.

Parameters:
pd - an array of PackageDoc objects

processClasses

public void processClasses(ClassDoc[] cd,
                           java.lang.String pkgName)
Process classes and interfaces.

Parameters:
cd - An array of ClassDoc objects.

addCommonModifiers

public void addCommonModifiers(ProgramElementDoc ped,
                               int indent)
Add qualifiers for the program element as attributes.

Parameters:
ped - The given program element.

addSourcePosition

public void addSourcePosition(ProgramElementDoc ped,
                              int indent)
Insert the source code details, if available.

Parameters:
ped - The given program element.

processInterfaces

public void processInterfaces(java.lang.reflect.Type[] ifaces)
Process the interfaces implemented by the class.

Parameters:
ifaces - An array of ClassDoc objects

processConstructors

public void processConstructors(ConstructorDoc[] ct)
Process the constructors in the class.

Parameters:
ct - An array of ConstructorDoc objects

processExceptions

public void processExceptions(ClassDoc[] cd)
Process all exceptions thrown by a constructor or method.

Parameters:
cd - An array of ClassDoc objects

processMethods

public void processMethods(ClassDoc cd,
                           MethodDoc[] md)
Process the methods in the class.

Parameters:
md - An array of MethodDoc objects

processFields

public void processFields(FieldDoc[] fd)
Process the fields in the class.

Parameters:
fd - An array of FieldDoc objects

emitType

public void emitType(com.sun.javadoc.Type type)
Emit the type name. Removed any prefixed warnings about ambiguity. The type maybe an array.

Parameters:
type - A Type object.

emitXMLHeader

public void emitXMLHeader()
Emit the XML header.


emitXMLFooter

public void emitXMLFooter()
Emit the XML footer.


shownElement

public boolean shownElement(Doc doc,
                            java.lang.String visLevel)
Determine if the program element is shown, according to the given level of visibility.

Parameters:
ped - The given program element.
visLevel - The desired visibility level; "public", "protected", "package" or "private". If null, only check for an exclude tag.
Returns:
boolean Set if this element is shown.

stripNonPrintingChars

public java.lang.String stripNonPrintingChars(java.lang.String s,
                                              Doc doc)
Strip out non-printing characters, replacing them with a character which will not change where the end of the first sentence is found. This character is the hash mark, '#'.


inRange

public boolean inRange(int val,
                       int min,
                       int max)
Return true if val is in the range [min|max], inclusive.


addDocumentation

public void addDocumentation(ProgramElementDoc ped,
                             int indent)
Add at least the first sentence from a doc block to the API. This is used by the report generator if no comment is provided. Need to make sure that HTML tags are not confused with XML tags. This could be done by stuffing the < character to another string or by handling HTML in the parser. This second option seems neater. Note that XML expects all element tags to have either a closing "/>" or a matching end element tag. Due to the difficulties of converting incorrect HTML to XHTML, the first option is used.


addPkgDocumentation

public void addPkgDocumentation(RootDoc root,
                                PackageDoc pd,
                                int indent)
Add at least the first sentence from a doc block for a package to the API. This is used by the report generator if no comment is provided. The default source tree may not include the package.html files, so this may be unavailable in many cases. Need to make sure that HTML tags are not confused with XML tags. This could be done by stuffing the < character to another string or by handling HTML in the parser. This second option is neater. Note that XML expects all element tags to have either a closing "/>" or a matching end element tag. Due to the difficulties of converting incorrect HTML to XHTML, the first option is used.


endOfFirstSentence

public static int endOfFirstSentence(java.lang.String text)
Find the index of the end of the first sentence in the given text, when writing out to an XML file. This is an extended version of the algorithm used by the DocCheck Javadoc doclet. It checks for @tags too.

Parameters:
text - The text to be searched.
Returns:
The index of the end of the first sentence. If there is no end, return -1. If there is no useful text, return 0. If the whole doc block comment is wanted (default), return -1.

endOfFirstSentence

public static int endOfFirstSentence(java.lang.String text,
                                     boolean writingToXML)
Find the index of the end of the first sentence in the given text. This is an extended version of the algorithm used by the DocCheck Javadoc doclet. It checks for @tags too.

Parameters:
text - The text to be searched.
writingToXML - Set to true when writing out XML.
Returns:
The index of the end of the first sentence. If there is no end, return -1. If there is no useful text, return 0. If the whole doc block comment is wanted (default), return -1.

minIndex

public static int minIndex(int i,
                           int j)
Return the minimum of two indexes if > -1, and return -1 only if both indexes = -1.

Parameters:
i - an int index
j - an int index
Returns:
an int equal to the minimum index > -1, or -1