Package uk.ac.starlink.ttools.build

Class FullXmlDoclet

  • public class FullXmlDoclet
extends XmlDoclet
    Doclet which documents public static members of classes in XML for insertion into SUN-style XML user documents.

    Optional doclet flags beyond the standard ones are:

    -headonly
    Write only the class headers, not information about the methods themselves.
    Since:
    22 Apr 2005
    Author:
    Mark Taylor (Starlink)

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected FullXmlDoclet​(com.sun.javadoc.RootDoc root)
      Constructor.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void endClass()
      End output of documentation for the most recently started class.
      protected void endMember()
      End output of the most recently started member.
      protected java.lang.String getXmlId​(com.sun.javadoc.ClassDoc clazz)
      Returns the value to use for the XML ID attached to the subsection describing a given class.
      static int optionLength​(java.lang.String option)
      Define permitted command-line flags.
      void out​(java.lang.String line)
      Outputs a single line of output to the current output stream.
      protected void outDescription​(java.lang.String desc)
      Output a description item.
      protected void outExamples​(java.lang.String[] examples)
      Output examples of the current documentandum (presumably a method).
      protected void outParameters​(com.sun.javadoc.Parameter[] params, java.lang.String[] comments, boolean isVararg)
      Output parameters to the current documentandum (presumably a method).
      protected void outReturn​(com.sun.javadoc.Type rtype, java.lang.String rdesc)
      Output return value for the current method.
      protected void outSees​(com.sun.javadoc.SeeTag[] seeTags)
      Output any See tags from the current documentandum.
      protected boolean process()
      Works through the root document invoking the various protected methods to produce output.
      static boolean start​(com.sun.javadoc.RootDoc root)
      Begin processing document.
      protected void startClass​(com.sun.javadoc.ClassDoc clazz)
      Begin output of documentation for a given class.
      protected void startMember​(com.sun.javadoc.MemberDoc mem, java.lang.String memType, java.lang.String memName)
      Begin output of documentation for a given class member (field or method).
      protected boolean useClass​(com.sun.javadoc.ClassDoc clazz)
      Indicates whether a given class should be documented by this doclet or ignored.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • FullXmlDoclet

        protected FullXmlDoclet​(com.sun.javadoc.RootDoc root)
                 throws java.io.IOException
        Constructor.
        Parameters:
        root - root document
        Throws:
        java.io.IOException

    • Method Detail

      • start

        public static boolean start​(com.sun.javadoc.RootDoc root)
                     throws java.io.IOException
        Begin processing document. This method is part of the Doclet public interface.
        Throws:
        java.io.IOException

      • optionLength

        public static int optionLength​(java.lang.String option)
        Define permitted command-line flags. This method is part of the Doclet public interface.

      • getXmlId

        protected java.lang.String getXmlId​(com.sun.javadoc.ClassDoc clazz)
        Returns the value to use for the XML ID attached to the subsection describing a given class.
        Parameters:
        clazz - class doc
        Returns:
        XML ID string

      • useClass

        protected boolean useClass​(com.sun.javadoc.ClassDoc clazz)
        Indicates whether a given class should be documented by this doclet or ignored. The default implementation returns true always, but it may be overridden by subclasses.
        Parameters:
        clazz - class doc
        Returns:
        true to use class, false to ignore it

      • process

        protected boolean process()
                   throws java.io.IOException
        Description copied from class: MemberDoclet
        Works through the root document invoking the various protected methods to produce output.
        Overrides:
        process in class MemberDoclet
        Throws:
        java.io.IOException

      • startClass

        protected void startClass​(com.sun.javadoc.ClassDoc clazz)
                   throws java.io.IOException
        Description copied from class: MemberDoclet
        Begin output of documentation for a given class. Subsequent calls to outItem refer to this.
        Overrides:
        startClass in class XmlDoclet
        Parameters:
        clazz - class to document
        Throws:
        java.io.IOException

      • endClass

        protected void endClass()
                 throws java.io.IOException
        Description copied from class: MemberDoclet
        End output of documentation for the most recently started class.
        Overrides:
        endClass in class XmlDoclet
        Throws:
        java.io.IOException

      • startMember

        protected void startMember​(com.sun.javadoc.MemberDoc mem,
                           java.lang.String memType,
                           java.lang.String memName)
                    throws java.io.IOException
        Description copied from class: MemberDoclet
        Begin output of documentation for a given class member (field or method). Subsequent calls to outItem etc refer to this.
        Overrides:
        startMember in class XmlDoclet
        Parameters:
        mem - class member
        memType - some user-viewable (that is not necessarily using technical terms) description of what kind of member it is
        memName - some user-viewable label for the member
        Throws:
        java.io.IOException

      • endMember

        protected void endMember()
                  throws java.io.IOException
        Description copied from class: MemberDoclet
        End output of the most recently started member.
        Overrides:
        endMember in class XmlDoclet
        Throws:
        java.io.IOException

      • outDescription

        protected void outDescription​(java.lang.String desc)
                       throws java.io.IOException
        Description copied from class: MemberDoclet
        Output a description item.
        Overrides:
        outDescription in class XmlDoclet
        Parameters:
        desc - description string
        Throws:
        java.io.IOException

      • outParameters

        protected void outParameters​(com.sun.javadoc.Parameter[] params,
                             java.lang.String[] comments,
                             boolean isVararg)
                      throws java.io.IOException
        Description copied from class: MemberDoclet
        Output parameters to the current documentandum (presumably a method).
        Overrides:
        outParameters in class XmlDoclet
        Parameters:
        params - array of Parameter objects
        comments - array of comment strings matching params; if there's no comment, the element may be null
        isVararg - true if the method is known to have its final formal argument declared with variable length
        Throws:
        java.io.IOException

      • outReturn

        protected void outReturn​(com.sun.javadoc.Type rtype,
                         java.lang.String rdesc)
                  throws java.io.IOException
        Description copied from class: MemberDoclet
        Output return value for the current method.
        Overrides:
        outReturn in class XmlDoclet
        Parameters:
        rtype - type of return value
        rdesc - text of return value description (may be null)
        Throws:
        java.io.IOException

      • outExamples

        protected void outExamples​(java.lang.String[] examples)
                    throws java.io.IOException
        Description copied from class: MemberDoclet
        Output examples of the current documentandum (presumably a method).
        Overrides:
        outExamples in class XmlDoclet
        Parameters:
        examples - array of strings each representing an example
        Throws:
        java.io.IOException

      • outSees

        protected void outSees​(com.sun.javadoc.SeeTag[] seeTags)
                throws java.io.IOException
        Description copied from class: MemberDoclet
        Output any See tags from the current documentandum. This only includes explicit @see tags, not @links.
        Overrides:
        outSees in class XmlDoclet
        Throws:
        java.io.IOException
        See Also:
        contents

      • out

        public void out​(java.lang.String line)
         throws java.io.IOException
        Outputs a single line of output to the current output stream.
        Overrides:
        out in class XmlDoclet
        Parameters:
        line - text for output
        Throws:
        java.io.IOException