Package uk.ac.starlink.ttools.build

Class MemberDoclet

  • Direct Known Subclasses:
    HtmlDoclet, XmlDoclet
    public abstract class MemberDoclet
extends java.lang.Object
    Abstract superclass for doclets which document the static public members of classes which are to be made available at runtime in TOPCAT using JEL. This class deals with going through the root document as presented by the (generic) Doclet application and presenting the useful bits (mainly: static public methods and fields) for output. Concrete subclasses must implement methods to do the actual output.
    Since:
    1 Sep 2004
    Author:
    Mark Taylor (Starlink)

    • Constructor Summary

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

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected abstract void endClass()
      End output of documentation for the most recently started class.
      protected abstract void endMember()
      End output of the most recently started member.
      boolean isDocumentable​(com.sun.javadoc.ProgramElementDoc pel)
      Indicates whether a given item is to be documented or ignored.
      static com.sun.javadoc.LanguageVersion languageVersion()
      This magic static method appears to be required to make the isVarArgs() method on com.sun.javadoc.ExecutableMemberDoc report variable argument status.
      protected abstract void outDescription​(java.lang.String descrip)
      Output a description item.
      protected abstract void outExamples​(java.lang.String[] examples)
      Output examples of the current documentandum (presumably a method).
      protected abstract void outItem​(java.lang.String name, java.lang.String val)
      Output an item to the current documentandum (class/member).
      protected abstract void outParameters​(com.sun.javadoc.Parameter[] params, java.lang.String[] comments, boolean isVararg)
      Output parameters to the current documentandum (presumably a method).
      protected abstract void outReturn​(com.sun.javadoc.Type rtype, java.lang.String rdesc)
      Output return value for the current method.
      protected abstract 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.
      protected void processClass​(com.sun.javadoc.ClassDoc clazz)
      Generates documentation for a given class.
      protected void processPackage​(com.sun.javadoc.PackageDoc pack)
      Generates documentation for a given package.
      static java.lang.String pWrap​(java.lang.String text)
      Ensures that a string is a sequence of <p> elements (though it's not foolproof).
      protected abstract void startClass​(com.sun.javadoc.ClassDoc clazz)
      Begin output of documentation for a given class.
      protected abstract 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).
      static java.lang.String typeString​(com.sun.javadoc.Type type)
      Returns a string suitable for user consumption which describes a non-varargs Type.
      static java.lang.String varargTypeString​(com.sun.javadoc.Type type, boolean isVararg)
      Returns a string suitable for user consumption which describes a type that may or may not represent a variable-argument parameter.
      static void warning​(java.lang.String msg)
      Log a warning.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • MemberDoclet

        protected MemberDoclet​(com.sun.javadoc.RootDoc root)
        Constructor.

    • Method Detail

      • startClass

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

      • endClass

        protected abstract void endClass()
                          throws java.io.IOException
        End output of documentation for the most recently started class.
        Throws:
        java.io.IOException

      • startMember

        protected abstract void startMember​(com.sun.javadoc.MemberDoc mem,
                                    java.lang.String memType,
                                    java.lang.String memName)
                             throws java.io.IOException
        Begin output of documentation for a given class member (field or method). Subsequent calls to outItem etc refer to this.
        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 abstract void endMember()
                           throws java.io.IOException
        End output of the most recently started member.
        Throws:
        java.io.IOException

      • outItem

        protected abstract void outItem​(java.lang.String name,
                                java.lang.String val)
                         throws java.io.IOException
        Output an item to the current documentandum (class/member).
        Parameters:
        name - item title
        val - item content (HTML text)
        Throws:
        java.io.IOException

      • outParameters

        protected abstract void outParameters​(com.sun.javadoc.Parameter[] params,
                                      java.lang.String[] comments,
                                      boolean isVararg)
                               throws java.io.IOException
        Output parameters to the current documentandum (presumably a method).
        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 abstract void outReturn​(com.sun.javadoc.Type rtype,
                                  java.lang.String rdesc)
                           throws java.io.IOException
        Output return value for the current method.
        Parameters:
        rtype - type of return value
        rdesc - text of return value description (may be null)
        Throws:
        java.io.IOException

      • outExamples

        protected abstract void outExamples​(java.lang.String[] examples)
                             throws java.io.IOException
        Output examples of the current documentandum (presumably a method).
        Parameters:
        examples - array of strings each representing an example
        Throws:
        java.io.IOException

      • outSees

        protected abstract void outSees​(com.sun.javadoc.SeeTag[] seeTags)
                         throws java.io.IOException
        Output any See tags from the current documentandum. This only includes explicit @see tags, not @links.
        Parameters:
        seeTags -
        Throws:
        java.io.IOException
        See Also:
        contents

      • outDescription

        protected abstract void outDescription​(java.lang.String descrip)
                                throws java.io.IOException
        Output a description item.
        Parameters:
        descrip - description string
        Throws:
        java.io.IOException

      • process

        protected boolean process()
                   throws java.io.IOException
        Works through the root document invoking the various protected methods to produce output.
        Throws:
        java.io.IOException

      • processPackage

        protected void processPackage​(com.sun.javadoc.PackageDoc pack)
                       throws java.io.IOException
        Generates documentation for a given package.
        Parameters:
        pack - package
        Throws:
        java.io.IOException

      • processClass

        protected void processClass​(com.sun.javadoc.ClassDoc clazz)
                     throws java.io.IOException
        Generates documentation for a given class.
        Parameters:
        clazz - class
        Throws:
        java.io.IOException

      • isDocumentable

        public boolean isDocumentable​(com.sun.javadoc.ProgramElementDoc pel)
        Indicates whether a given item is to be documented or ignored. Currently, members that are public, static, and not marked by the @HideDoc annotation are considered documentable. Fields must additionally be declared final.
        Parameters:
        pel - program element
        Returns:
        true to process for documentation, false to skip

      • languageVersion

        public static com.sun.javadoc.LanguageVersion languageVersion()
        This magic static method appears to be required to make the isVarArgs() method on com.sun.javadoc.ExecutableMemberDoc report variable argument status. I don't know whether or where that's documented, but I found out from StackOverflow.
        Returns:
        LanguageVersion.JAVA_1_5

      • typeString

        public static java.lang.String typeString​(com.sun.javadoc.Type type)
        Returns a string suitable for user consumption which describes a non-varargs Type.
        Parameters:
        type - type
        Returns:
        string representation of type (non-technical?)

      • varargTypeString

        public static java.lang.String varargTypeString​(com.sun.javadoc.Type type,
                                                boolean isVararg)
        Returns a string suitable for user consumption which describes a type that may or may not represent a variable-argument parameter.
        Parameters:
        type - type
        isVararg - true if type is known to describe a variable-argument parameter
        Returns:
        string representation of type (non-technical?)

      • pWrap

        public static java.lang.String pWrap​(java.lang.String text)
        Ensures that a string is a sequence of <p> elements (though it's not foolproof).
        Parameters:
        text - basic text
        Returns:
        same as text but a sequence of HTML P elements

      • warning

        public static void warning​(java.lang.String msg)
        Log a warning.
        Parameters:
        msg - message