Package uk.ac.starlink.ttools.build

Class FullXmlDoclet

java.lang.Object
uk.ac.starlink.ttools.build.MemberDoclet
uk.ac.starlink.ttools.build.XmlDoclet
uk.ac.starlink.ttools.build.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 first sentence of the class headers, and not information about the methods.
Since:
22 Apr 2005
Author:
Mark Taylor (Starlink)

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    FullXmlDoclet(RootDoc root)
    Constructor.

  • Method Summary

    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 String
    getXmlId(ClassDoc clazz)
    Returns the value to use for the XML ID attached to the subsection describing a given class.
    static int
    optionLength(String option)
    Define permitted command-line flags.
    void
    out(String line)
    Outputs a single line of output to the current output stream.
    protected void
    outDescription(String desc)
    Output a description item.
    protected void
    outExamples(String[] examples)
    Output examples of the current documentandum (presumably a method).
    protected void
    outParameters(Parameter[] params, String[] comments, boolean isVararg)
    Output parameters to the current documentandum (presumably a method).
    protected void
    outReturn(Type rtype, String rdesc)
    Output return value for the current method.
    protected void
    outSees(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(RootDoc root)
    Begin processing document.
    protected void
    startClass(ClassDoc clazz)
    Begin output of documentation for a given class.
    protected void
    startMember(MemberDoc mem, String memType, String memName)
    Begin output of documentation for a given class member (field or method).
    protected boolean
    useClass(ClassDoc clazz)
    Indicates whether a given class should be documented by this doclet or ignored.

    Methods inherited from class uk.ac.starlink.ttools.build.XmlDoclet

    doctorText, flush, out, outItem

    Methods inherited from class uk.ac.starlink.ttools.build.MemberDoclet

    firstSentence, isDocumentable, languageVersion, processClass, processPackage, pWrap, typeString, varargTypeString, warning

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • FullXmlDoclet

      protected FullXmlDoclet(RootDoc root) throws IOException
      Constructor.
      Parameters:
      root - root document
      Throws:
      IOException

  • Method Details

    • start

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

    • optionLength

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

    • getXmlId

      protected String getXmlId(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(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 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:
      IOException

    • startClass

      protected void startClass(ClassDoc clazz) throws 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:
      IOException

    • endClass

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

    • startMember

      protected void startMember(MemberDoc mem, String memType, String memName) throws 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:
      IOException

    • endMember

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

    • outDescription

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

    • outParameters

      protected void outParameters(Parameter[] params, String[] comments, boolean isVararg) throws 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:
      IOException

    • outReturn

      protected void outReturn(Type rtype, String rdesc) throws 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:
      IOException

    • outExamples

      protected void outExamples(String[] examples) throws 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:
      IOException

    • outSees

      protected void outSees(SeeTag[] seeTags) throws 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:
      IOException
      See Also:
      • contents

    • out

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