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 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 theisVarArgs()
method oncom.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.
-
-
-
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 membermemType
- some user-viewable (that is not necessarily using technical terms) description of what kind of member it ismemName
- 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 titleval
- 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 objectscomments
- array of comment strings matching params; if there's no comment, the element may be nullisVararg
- 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 valuerdesc
- 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 theisVarArgs()
method oncom.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
- typeisVararg
- 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
-
-