Package jdiff

Class 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

      Fields 
      Modifier and Type Field Description
      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

      Constructors 
      Constructor Description
      RootDocToXML()
      Default constructor.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addCommonModifiers​(com.sun.javadoc.ProgramElementDoc ped, int indent)
      Add qualifiers for the program element as attributes.
      void addDocumentation​(com.sun.javadoc.ProgramElementDoc ped, int indent)
      Add at least the first sentence from a doc block to the API.
      void addPkgDocumentation​(com.sun.javadoc.RootDoc root, com.sun.javadoc.PackageDoc pd, int indent)
      Add at least the first sentence from a doc block for a package to the API.
      void addSourcePosition​(com.sun.javadoc.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​(com.sun.javadoc.ClassDoc[] cd, java.lang.String pkgName)
      Process classes and interfaces.
      void processConstructors​(com.sun.javadoc.ConstructorDoc[] ct)
      Process the constructors in the class.
      void processExceptions​(com.sun.javadoc.ClassDoc[] cd)
      Process all exceptions thrown by a constructor or method.
      void processFields​(com.sun.javadoc.FieldDoc[] fd)
      Process the fields in the class.
      void processInterfaces​(com.sun.javadoc.Type[] ifaces)
      Process the interfaces implemented by the class.
      void processMethods​(com.sun.javadoc.ClassDoc cd, com.sun.javadoc.MethodDoc[] md)
      Process the methods in the class.
      void processPackages​(com.sun.javadoc.RootDoc root)
      Process each package and the classes/interfaces within it.
      boolean shownElement​(com.sun.javadoc.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, com.sun.javadoc.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​(com.sun.javadoc.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​(com.sun.javadoc.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​(com.sun.javadoc.RootDoc root)
        Process each package and the classes/interfaces within it.
        Parameters:
        pd - an array of PackageDoc objects

      • processClasses

        public void processClasses​(com.sun.javadoc.ClassDoc[] cd,
                           java.lang.String pkgName)
        Process classes and interfaces.
        Parameters:
        cd - An array of ClassDoc objects.

      • addCommonModifiers

        public void addCommonModifiers​(com.sun.javadoc.ProgramElementDoc ped,
                               int indent)
        Add qualifiers for the program element as attributes.
        Parameters:
        ped - The given program element.

      • addSourcePosition

        public void addSourcePosition​(com.sun.javadoc.ProgramElementDoc ped,
                              int indent)
        Insert the source code details, if available.
        Parameters:
        ped - The given program element.

      • processInterfaces

        public void processInterfaces​(com.sun.javadoc.Type[] ifaces)
        Process the interfaces implemented by the class.
        Parameters:
        ifaces - An array of ClassDoc objects

      • processConstructors

        public void processConstructors​(com.sun.javadoc.ConstructorDoc[] ct)
        Process the constructors in the class.
        Parameters:
        ct - An array of ConstructorDoc objects

      • processExceptions

        public void processExceptions​(com.sun.javadoc.ClassDoc[] cd)
        Process all exceptions thrown by a constructor or method.
        Parameters:
        cd - An array of ClassDoc objects

      • processMethods

        public void processMethods​(com.sun.javadoc.ClassDoc cd,
                           com.sun.javadoc.MethodDoc[] md)
        Process the methods in the class.
        Parameters:
        md - An array of MethodDoc objects

      • processFields

        public void processFields​(com.sun.javadoc.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​(com.sun.javadoc.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,
                                              com.sun.javadoc.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​(com.sun.javadoc.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​(com.sun.javadoc.RootDoc root,
                                com.sun.javadoc.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