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 String | apiIdentifier
The identifier of the API being written out in XML, e.g.
|
static String | baseURI
The base URI for locating necessary DTDs and Schemas. |
static 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 String | excludeTag
Exclude program elements marked with this String, e.g. |
static String | memberVisibilityLevel
Do not display a member with a lower level of visibility than this.
|
static String | outputDirectory
The name of the directory where the XML representing the API will be
stored. |
static 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. |
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(Type type)
Emit the type name. |
void | emitXMLFooter()
Emit the XML footer. |
void | emitXMLHeader()
Emit the XML header. |
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.
|
static int | endOfFirstSentence(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, 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(ClassDoc[] 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, String visLevel)
Determine if the program element is shown, according to the given
level of visibility.
|
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.
|
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. |
public static String apiIdentifier
The identifier of the API being written out in XML, e.g.
"SuperProduct 1.3".
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"
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.
public static boolean doExclude
If set, exclude program elements marked with whatever the exclude tag
is specified as, e.g. "@exclude".
public static String excludeTag
Exclude program elements marked with this String, e.g. "@exclude".
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).
public static String outputDirectory
The name of the directory where the XML representing the API will be
stored.
public static String outputFileName
The name of the file where the XML representing the API will be
stored.
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.
public RootDocToXML()
Default constructor.
public void addCommonModifiers(ProgramElementDoc ped, int indent)
Add qualifiers for the program element as attributes.
Parameters: ped The given program element.
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.
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.
public void addSourcePosition(ProgramElementDoc ped, int indent)
Insert the source code details, if available.
Parameters: ped The given program element.
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.
public void emitXMLFooter()
Emit the XML footer.
public void emitXMLHeader()
Emit the XML header.
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.
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.
public boolean inRange(int val, int min, int max)
Return true if val is in the range [min|max], inclusive.
public void logOptions()
Write the options which were used to generate this XML file
out as XML comments.
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
public void processClasses(ClassDoc[] cd, String pkgName)
Process classes and interfaces.
Parameters: cd An array of ClassDoc objects.
public void processConstructors(ConstructorDoc[] ct)
Process the constructors in the class.
Parameters: ct An array of ConstructorDoc objects
public void processExceptions(ClassDoc[] cd)
Process all exceptions thrown by a constructor or method.
Parameters: cd An array of ClassDoc objects
public void processFields(FieldDoc[] fd)
Process the fields in the class.
Parameters: fd An array of FieldDoc objects
public void processInterfaces(ClassDoc[] ifaces)
Process the interfaces implemented by the class.
Parameters: ifaces An array of ClassDoc objects
public void processMethods(ClassDoc cd, MethodDoc[] md)
Process the methods in the class.
Parameters: md An array of MethodDoc objects
public void processPackages(RootDoc root)
Process each package and the classes/interfaces within it.
Parameters: pd an array of PackageDoc objects
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.
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, '#'.
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
public static void writeXSD()
Write the XML Schema file used for validation.