Package uk.ac.starlink.ttools.build

Class XmlDoclet

  • Direct Known Subclasses:
    FullXmlDoclet
    public abstract class XmlDoclet
extends MemberDoclet
    Doclet which documents public static members of classes in SUN-type XML. This abstract superclass provides basic XML-type doclet functionality.

    Optional doclet flags beyond the standard ones are:

    -o file
    Specify output file
    Since:
    6 Sep 2004
    Author:
    Mark Taylor (Starlink)

    • Constructor Summary

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

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static java.lang.String doctorText​(java.lang.String text)
      Attempts to turn HTML text into XML.
      protected void endClass()
      End output of documentation for the most recently started class.
      protected void endMember()
      End output of the most recently started member.
      void flush()  
      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.
      void out​(java.lang.String[] lines)
      Outputs some lines of text to the current output stream.
      protected void outDescription​(java.lang.String descrip)
      Output a description item.
      protected void outExamples​(java.lang.String[] examples)
      Output examples of the current documentandum (presumably a method).
      protected void outItem​(java.lang.String name, java.lang.String val)
      Output an item to the current documentandum (class/member).
      protected void outParameters​(com.sun.javadoc.Parameter[] param, 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 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).

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • XmlDoclet

        protected XmlDoclet​(com.sun.javadoc.RootDoc root)
             throws java.io.IOException
        Throws:
        java.io.IOException

    • Method Detail

      • optionLength

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

      • 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.
        Specified by:
        startClass in class MemberDoclet
        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.
        Specified by:
        endClass in class MemberDoclet
        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.
        Specified by:
        startMember in class MemberDoclet
        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.
        Specified by:
        endMember in class MemberDoclet
        Throws:
        java.io.IOException

      • outDescription

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

      • outItem

        protected void outItem​(java.lang.String name,
                       java.lang.String val)
        Description copied from class: MemberDoclet
        Output an item to the current documentandum (class/member).
        Specified by:
        outItem in class MemberDoclet
        Parameters:
        name - item title
        val - item content (HTML text)

      • outParameters

        protected void outParameters​(com.sun.javadoc.Parameter[] param,
                             java.lang.String[] comments,
                             boolean isVararg)
                      throws java.io.IOException
        Description copied from class: MemberDoclet
        Output parameters to the current documentandum (presumably a method).
        Specified by:
        outParameters in class MemberDoclet
        Parameters:
        param - 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.
        Specified by:
        outReturn in class MemberDoclet
        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).
        Specified by:
        outExamples in class MemberDoclet
        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.
        Specified by:
        outSees in class MemberDoclet
        Throws:
        java.io.IOException
        See Also:
        contents

      • out

        public void out​(java.lang.String[] lines)
         throws java.io.IOException
        Outputs some lines of text to the current output stream. Implemented in terms of out(java.lang.String).
        Parameters:
        lines - text for output
        Throws:
        java.io.IOException

      • out

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

      • flush

        public void flush()
           throws java.io.IOException
        Throws:
        java.io.IOException

      • doctorText

        public static java.lang.String doctorText​(java.lang.String text)
        Attempts to turn HTML text into XML. It's pretty ad-hoc, and many things can go wrong with it - using this relies on the various document tests picking up anything that goes wrong.
        Parameters:
        text - HTML-type text
        Returns:
        XML-type text