Package uk.ac.starlink.ttools.build

Class MemberDoclet

java.lang.Object
uk.ac.starlink.ttools.build.MemberDoclet
Direct Known Subclasses:
HtmlDoclet, XmlDoclet
public abstract class MemberDoclet extends 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(RootDoc root)
    Constructor.

  • Method Summary

    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.
    static String
    firstSentence(Doc doc)
    Returns the first sentence of documentation for a Doc element as plain text.
    boolean
    isDocumentable(ProgramElementDoc pel)
    Indicates whether a given item is to be documented or ignored.
    static 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(String descrip)
    Output a description item.
    protected abstract void
    outExamples(String[] examples)
    Output examples of the current documentandum (presumably a method).
    protected abstract void
    outItem(String name, String val)
    Output an item to the current documentandum (class/member).
    protected abstract void
    outParameters(Parameter[] params, String[] comments, boolean isVararg)
    Output parameters to the current documentandum (presumably a method).
    protected abstract void
    outReturn(Type rtype, String rdesc)
    Output return value for the current method.
    protected abstract 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.
    protected void
    processClass(ClassDoc clazz)
    Generates documentation for a given class.
    protected void
    processPackage(PackageDoc pack)
    Generates documentation for a given package.
    static String
    pWrap(String text)
    Ensures that a string is a sequence of <p> elements (though it's not foolproof).
    protected abstract void
    startClass(ClassDoc clazz)
    Begin output of documentation for a given class.
    protected abstract void
    startMember(MemberDoc mem, String memType, String memName)
    Begin output of documentation for a given class member (field or method).
    static String
    typeString(Type type)
    Returns a string suitable for user consumption which describes a non-varargs Type.
    static String
    varargTypeString(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(String msg)
    Log a warning.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • MemberDoclet

      protected MemberDoclet(RootDoc root)
      Constructor.

  • Method Details

    • startClass

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

    • endClass

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

    • startMember

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

    • endMember

      protected abstract void endMember() throws IOException
      End output of the most recently started member.
      Throws:
      IOException

    • outItem

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

    • outParameters

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

    • outReturn

      protected abstract void outReturn(Type rtype, String rdesc) throws IOException
      Output return value for the current method.
      Parameters:
      rtype - type of return value
      rdesc - text of return value description (may be null)
      Throws:
      IOException

    • outExamples

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

    • outSees

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

    • outDescription

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

    • process

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

    • processPackage

      protected void processPackage(PackageDoc pack) throws IOException
      Generates documentation for a given package.
      Parameters:
      pack - package
      Throws:
      IOException

    • processClass

      protected void processClass(ClassDoc clazz) throws IOException
      Generates documentation for a given class.
      Parameters:
      clazz - class
      Throws:
      IOException

    • isDocumentable

      public boolean isDocumentable(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 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 String typeString(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 String varargTypeString(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 String pWrap(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

    • firstSentence

      public static String firstSentence(Doc doc)
      Returns the first sentence of documentation for a Doc element as plain text. Tags are ignored.
      Parameters:
      doc - documented item
      Returns:
      first sentence of text

    • warning

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