uk.ac.starlink.ttools.build
Class MemberDoclet

java.lang.Object
  extended by 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
protected MemberDoclet(RootDoc root)
          Constructor.
 
Method Summary
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.
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)
          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  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 clas member (field or method).
static String typeString(Type type)
          Returns a string suitable for user consumption which describes a Type.
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 Detail

MemberDoclet

protected MemberDoclet(RootDoc root)
Constructor.

Method Detail

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 clas 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)
                               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
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

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

typeString

public static String typeString(Type type)
Returns a string suitable for user consumption which describes a Type.

Parameters:
type - type
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

warning

public static void warning(String msg)
Log a warning.

Parameters:
msg - message


Copyright © 2015 Central Laboratory of the Research Councils. All Rights Reserved.