Package uk.ac.starlink.ttools.build
Class MemberDoclet
java.lang.Object
uk.ac.starlink.ttools.build.MemberDoclet
- Direct Known Subclasses:
HtmlDoclet
,XmlDoclet
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 -
Method Summary
Modifier and TypeMethodDescriptionprotected abstract void
endClass()
End output of documentation for the most recently started class.protected abstract void
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
This magic static method appears to be required to make theisVarArgs()
method oncom.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
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
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
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
Log a warning.
-
Constructor Details
-
MemberDoclet
protected MemberDoclet(RootDoc root) Constructor.
-
-
Method Details
-
startClass
Begin output of documentation for a given class. Subsequent calls to outItem refer to this.- Parameters:
clazz
- class to document- Throws:
IOException
-
endClass
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 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:
IOException
-
endMember
End output of the most recently started member.- Throws:
IOException
-
outItem
Output an item to the current documentandum (class/member).- Parameters:
name
- item titleval
- 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 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:
IOException
-
outReturn
Output return value for the current method.- Parameters:
rtype
- type of return valuerdesc
- text of return value description (may be null)- Throws:
IOException
-
outExamples
Output examples of the current documentandum (presumably a method).- Parameters:
examples
- array of strings each representing an example- Throws:
IOException
-
outSees
Output any See tags from the current documentandum. This only includes explicit @see tags, not @links.- Parameters:
seeTags
-- Throws:
IOException
- See Also:
-
contents
-
outDescription
Output a description item.- Parameters:
descrip
- description string- Throws:
IOException
-
process
Works through the root document invoking the various protected methods to produce output.- Throws:
IOException
-
processPackage
Generates documentation for a given package.- Parameters:
pack
- package- Throws:
IOException
-
processClass
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 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
Returns a string suitable for user consumption which describes a non-varargs Type.- Parameters:
type
- type- Returns:
- string representation of type (non-technical?)
-
varargTypeString
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
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
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
Log a warning.- Parameters:
msg
- message
-