Class OptionsDoclet
- java.lang.Object
-
- org.plumelib.options.OptionsDoclet
-
- All Implemented Interfaces:
jdk.javadoc.doclet.Doclet
public class OptionsDoclet extends java.lang.Object implements jdk.javadoc.doclet.Doclet
Generates HTML documentation of command-line options, for use in a manual or in a Javadoc class comment. Works with theOptions
class.Usage
This doclet is typically invoked with:
javadoc -quiet -doclet org.plumelib.options.OptionsDoclet [doclet options] [java files]
You must specify a docletpath to Javadoc, and it needs to include the class files for the documented classes.Doclet Options
The following doclet options are supported:
- -docfile file When specified, this doclet reads file and replaces
everything between the two lines
<!-- start options doc (DO NOT EDIT BY HAND) -->
and<!-- end options doc -->
in file with the options documentation. By default, produces output to standard out without modifying file; see-outfile
and-i
to output elsewhere or to edit file in place. - -outfile file The destination for the output (the default is standard out).
If both
-outfile
and-docfile
are specified, they must be different (but see the-i
option). When-d
is used, the output is written to a file with the given name relative to that destination directory. - -d directory The destination directory for the output file. Only used if
-outfile
is used, in which case the file is written in this directory. - -i Specifies that the docfile should be edited in-place. This option can only be
used if the
-docfile
option is used, and may not be used at the same time as the-outfile
option. - -format format This option sets the output format of this doclet. Currently,
the following values for format are supported:
- javadoc When this format is specified, the output of this doclet is formatted
as a Javadoc comment, with "*" at the beginning of each line and (when used with the
-docfile
option) using appropriate indentation. Inline@link
and@see
tags in the Javadoc input are left untouched. - html This format outputs HTML for general-purpose use, meaning inline
@link
and@see
tags in the Javadoc input are suitably replaced by HTML links. This is the default output format and need not be specified explicitly.
- javadoc When this format is specified, the output of this doclet is formatted
as a Javadoc comment, with "*" at the beginning of each line and (when used with the
- -classdoc When specified, the output of this doclet includes the class documentation of the first class specified on the command-line.
- -singledash When specified,
setUseSingleDash(true)
is called on the underlying instance of Options used to generate documentation.
Examples
Search for "OptionsDoclet" in the buildfiles for Lookup, Randoop, and Javarifier.
Requirements
Classes passed to OptionsDoclet that have
@
Option
annotations on non-static fields should have a nullary (no-argument) constructor. The nullary constructor may be private or public. This is required because an object instance is needed to get the default value of a non-static field. It is cleaner to require a nullary constructor instead of trying to guess arguments to pass to another constructor.Hiding default value strings
By default, the documentation generated by OptionsDoclet includes a default value string for each option, in square brackets after the option's description, similar to the usage messages generated by
Options.usage(String...)
. To omit the default value for an option that has a system-dependent default, set theOption.noDocDefault()
field totrue
:/** * <other stuff...> This option defaults to the system timezone. */ @Option(value="<timezone> Set the timezone", noDocDefault=true) public static String timezone = TimeZone.getDefault().getID();
Suppose that HTML documentation is generated in Chicago. WithoutnoDocDefault
, the HTML documentation would incorrectly state that the default time zone is"America/Chicago"
, which is incorrect for users elsewhere. UsingnoDocDefault
keeps the HTML documentation system-agnostic.Uppublicized options
The generated HTML documentation omits
@
Unpublicized
options. It includes unpublicized option groups if they contain any publicized options.Troubleshooting
If you get an error such as "
ARGH! @Option
", then you are using a buggy version of gjdoc, the GNU Classpath implementation of Javadoc. To avoid the problem, upgrade or use a different Javadoc implementation.- See Also:
Option
,Options
,OptionGroup
,Unpublicized
-
-
Constructor Summary
Constructors Constructor Description OptionsDoclet()
Create an OptionsDoclet.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static java.lang.String
docCommentToHtml(com.sun.source.doctree.DocCommentTree docCommentTree)
Replace the @link tags and block @see tags in a Javadoc comment with HTML.static @BinaryName java.lang.String
getBinaryName(javax.lang.model.element.TypeElement te)
Returns the binary name of the given type.boolean
getFormatJavadoc()
Returns true if the output format is Javadoc, false if the output format is HTML.java.lang.String
getName()
java.util.Set<? extends jdk.javadoc.doclet.Doclet.Option>
getSupportedOptions()
javax.lang.model.SourceVersion
getSupportedSourceVersion()
boolean
getUseSingleDash()
Return true if using a single dash (as opposed to a double dash) for command-line options.void
init(java.util.Locale locale, jdk.javadoc.doclet.Reporter reporter)
static boolean
isTypeElement(javax.lang.model.element.Element element)
Returns true if the given element kind is a type, i.e., a class, enum, interface, or annotation type.static int
optionLength(java.lang.String option)
Given a command-line option of this doclet, returns the number of arguments you must specify on the command line for the given option.java.lang.String
optionsToHtml(int refillWidth)
Get the HTML documentation for the underlying Options instance.java.lang.String
optionsToJavadoc(int padding, int refillWidth)
Get the HTML documentation for the underlying Options instance, formatted as a Javadoc comment.java.lang.String
optionToHtml(org.plumelib.options.Options.OptionInfo oi, int padding)
Get the line of HTML describing one Option.java.lang.String
output()
Get the final output of this doclet.void
processJavadoc()
Adds Javadoc info to each option inoptions.getOptions()
.boolean
run(jdk.javadoc.doclet.DocletEnvironment denv)
void
setFormatJavadoc(boolean val)
Supply true to set the output format to Javadoc, false to set the output format to HTML.void
setUseSingleDash(boolean val)
void
write()
Write the output of this doclet to the correct file.
-
-
-
Method Detail
-
init
public void init(java.util.Locale locale, jdk.javadoc.doclet.Reporter reporter)
- Specified by:
init
in interfacejdk.javadoc.doclet.Doclet
-
getName
public java.lang.String getName()
- Specified by:
getName
in interfacejdk.javadoc.doclet.Doclet
-
getSupportedOptions
public java.util.Set<? extends jdk.javadoc.doclet.Doclet.Option> getSupportedOptions()
- Specified by:
getSupportedOptions
in interfacejdk.javadoc.doclet.Doclet
-
getSupportedSourceVersion
public javax.lang.model.SourceVersion getSupportedSourceVersion()
- Specified by:
getSupportedSourceVersion
in interfacejdk.javadoc.doclet.Doclet
-
run
public boolean run(jdk.javadoc.doclet.DocletEnvironment denv)
- Specified by:
run
in interfacejdk.javadoc.doclet.Doclet
-
optionLength
public static int optionLength(java.lang.String option)
Given a command-line option of this doclet, returns the number of arguments you must specify on the command line for the given option. Returns 0 if the argument is not recognized. This method is automatically invoked by Javadoc.- Parameters:
option
- the command-line option- Returns:
- the number of command-line arguments needed when using the option
- See Also:
- Doclet overview
-
write
public void write() throws java.lang.Exception
Write the output of this doclet to the correct file.- Throws:
java.lang.Exception
- if there is trouble
-
output
public java.lang.String output() throws java.lang.Exception
Get the final output of this doclet. The string returned by this method is the output seen by the user.- Returns:
- the user-visible doclet output
- Throws:
java.lang.Exception
- if there is trouble
-
processJavadoc
public void processJavadoc()
Adds Javadoc info to each option inoptions.getOptions()
.
-
optionsToHtml
public java.lang.String optionsToHtml(int refillWidth)
Get the HTML documentation for the underlying Options instance.- Parameters:
refillWidth
- the number of columns to fit the text into, by breaking lines- Returns:
- the HTML documentation for the underlying Options instance
-
optionsToJavadoc
public java.lang.String optionsToJavadoc(int padding, int refillWidth)
Get the HTML documentation for the underlying Options instance, formatted as a Javadoc comment.- Parameters:
padding
- the number of leading spaces to add in the Javadoc output, before "* "refillWidth
- the number of columns to fit the text into, by breaking lines- Returns:
- the HTML documentation for the underlying Options instance
-
optionToHtml
public java.lang.String optionToHtml(org.plumelib.options.Options.OptionInfo oi, int padding)
Get the line of HTML describing one Option.- Parameters:
oi
- the option to describepadding
- the number of spaces to add at the begginning of the detail line (after the line with the option itself)- Returns:
- HTML describing oi
-
docCommentToHtml
public static java.lang.String docCommentToHtml(com.sun.source.doctree.DocCommentTree docCommentTree)
Replace the @link tags and block @see tags in a Javadoc comment with HTML.Currently, the output is non-hyperlinked HTML. This keeps most of the information in the comment while still being presentable. Ideally, @link/@see tags would be converted to HTML links that point to actual documentation.
- Parameters:
docCommentTree
- a Javadoc comment to convert to HTML- Returns:
- HTML version of doc
-
isTypeElement
public static boolean isTypeElement(javax.lang.model.element.Element element)
Returns true if the given element kind is a type, i.e., a class, enum, interface, or annotation type.- Parameters:
element
- the element to test- Returns:
- true, iff the given kind is a type kind
-
getBinaryName
public static @BinaryName java.lang.String getBinaryName(javax.lang.model.element.TypeElement te)
Returns the binary name of the given type.- Parameters:
te
- a type- Returns:
- the binary name of the type
-
getFormatJavadoc
public boolean getFormatJavadoc()
Returns true if the output format is Javadoc, false if the output format is HTML.- Returns:
- true if the output format is Javadoc, false if the output format is HTML
-
setFormatJavadoc
public void setFormatJavadoc(boolean val)
Supply true to set the output format to Javadoc, false to set the output format to HTML.- Parameters:
val
- true to set the output format to Javadoc, false to set the output format to HTML
-
getUseSingleDash
public boolean getUseSingleDash()
Return true if using a single dash (as opposed to a double dash) for command-line options.- Returns:
- whether to use a single dash (as opposed to a double dash) for command-line options
-
setUseSingleDash
public void setUseSingleDash(boolean val)
- Parameters:
val
- whether to use a single dash (as opposed to a double dash) for command-line options
-
-