MemberDoclet (Starjava TTOOLS API)

java.lang.Object
- uk.ac.starlink.ttools.build.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.

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.
`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 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
  - 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
  - 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

Class MemberDoclet

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

MemberDoclet

Method Detail

startClass

endClass

startMember

endMember

outItem

outParameters

outReturn

outExamples

outDescription

process

processPackage

processClass

languageVersion

typeString

varargTypeString

pWrap

warning