jdiff

Class RootDocToXML

public class RootDocToXML extends Object

Converts a Javadoc RootDoc object into a representation in an XML file. See the file LICENSE.txt for copyright details.
Field Summary
static StringapiIdentifier
The identifier of the API being written out in XML, e.g.
static StringbaseURI
The base URI for locating necessary DTDs and Schemas.
static StringclassVisibilityLevel
Do not display a class with a lower level of visibility than this.
static booleandoExclude
If set, exclude program elements marked with whatever the exclude tag is specified as, e.g.
static StringexcludeTag
Exclude program elements marked with this String, e.g.
static StringmemberVisibilityLevel
Do not display a member with a lower level of visibility than this.
static StringoutputDirectory
The name of the directory where the XML representing the API will be stored.
static StringoutputFileName
The name of the file where the XML representing the API will be stored.
static booleansaveAllDocs
If set, then save the entire contents of a doc block comment in the API file.
Constructor Summary
RootDocToXML()
Default constructor.
Method Summary
voidaddCommonModifiers(ProgramElementDoc ped, int indent)
Add qualifiers for the program element as attributes.
voidaddDocumentation(ProgramElementDoc ped, int indent)
Add at least the first sentence from a doc block to the API.
voidaddPkgDocumentation(RootDoc root, PackageDoc pd, int indent)
Add at least the first sentence from a doc block for a package to the API.
voidaddSourcePosition(ProgramElementDoc ped, int indent)
Insert the source code details, if available.
voidemitType(Type type)
Emit the type name.
voidemitXMLFooter()
Emit the XML footer.
voidemitXMLHeader()
Emit the XML header.
static intendOfFirstSentence(String text)
Find the index of the end of the first sentence in the given text, when writing out to an XML file.
static intendOfFirstSentence(String text, boolean writingToXML)
Find the index of the end of the first sentence in the given text.
booleaninRange(int val, int min, int max)
Return true if val is in the range [min|max], inclusive.
voidlogOptions()
Write the options which were used to generate this XML file out as XML comments.
static intminIndex(int i, int j)
Return the minimum of two indexes if > -1, and return -1 only if both indexes = -1.
voidprocessClasses(ClassDoc[] cd, String pkgName)
Process classes and interfaces.
voidprocessConstructors(ConstructorDoc[] ct)
Process the constructors in the class.
voidprocessExceptions(ClassDoc[] cd)
Process all exceptions thrown by a constructor or method.
voidprocessFields(FieldDoc[] fd)
Process the fields in the class.
voidprocessInterfaces(ClassDoc[] ifaces)
Process the interfaces implemented by the class.
voidprocessMethods(ClassDoc cd, MethodDoc[] md)
Process the methods in the class.
voidprocessPackages(RootDoc root)
Process each package and the classes/interfaces within it.
booleanshownElement(Doc doc, String visLevel)
Determine if the program element is shown, according to the given level of visibility.
StringstripNonPrintingChars(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 booleanwriteXML(RootDoc root)
Write the XML representation of the API to a file.
static voidwriteXSD()
Write the XML Schema file used for validation.

Field Detail

apiIdentifier

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

baseURI

public static 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"

classVisibilityLevel

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

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 String excludeTag
Exclude program elements marked with this String, e.g. "@exclude".

memberVisibilityLevel

public static 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).

outputDirectory

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

outputFileName

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

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.

Constructor Detail

RootDocToXML

public RootDocToXML()
Default constructor.

Method Detail

addCommonModifiers

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

Parameters: ped The given program element.

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.

addSourcePosition

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

Parameters: ped The given program element.

emitType

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

Parameters: type A Type object.

emitXMLFooter

public void emitXMLFooter()
Emit the XML footer.

emitXMLHeader

public void emitXMLHeader()
Emit the XML header.

endOfFirstSentence

public static int endOfFirstSentence(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(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.

inRange

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

logOptions

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

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

processClasses

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

Parameters: cd 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

processFields

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

Parameters: fd An array of FieldDoc objects

processInterfaces

public void processInterfaces(ClassDoc[] ifaces)
Process the interfaces implemented by the class.

Parameters: ifaces 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

processPackages

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

Parameters: pd an array of PackageDoc objects

shownElement

public boolean shownElement(Doc doc, 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 String stripNonPrintingChars(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, '#'.

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.