Class OptionsDoclet
- All Implemented Interfaces:
jdk.javadoc.doclet.Doclet
Options
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 the Option.noDocDefault()
field to true
:
/** * <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. Without noDocDefault
, the
HTML documentation would incorrectly state that the default time zone is
"America/Chicago"
, which is incorrect for users elsewhere. Using noDocDefault
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:
-
Nested Class Summary
Nested classes/interfaces inherited from interface jdk.javadoc.doclet.Doclet
jdk.javadoc.doclet.Doclet.Option
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic String
docCommentToHtml
(com.sun.source.doctree.DocCommentTree docCommentTree) Replace the @link tags and block @see tags in a Javadoc comment with HTML.static @BinaryName String
Returns the binary name of the given type.boolean
Returns true if the output format is Javadoc, false if the output format is HTML.getName()
Set<? extends jdk.javadoc.doclet.Doclet.Option>
boolean
Return true if using a single dash (as opposed to a double dash) for command-line options.void
static boolean
isTypeElement
(Element element) Returns true if the given element kind is a type, i.e., a class, enum, interface, or annotation type.optionsToHtml
(int refillWidth) Get the HTML documentation for the underlying Options instance.optionsToJavadoc
(int padding, int refillWidth) Get the HTML documentation for the underlying Options instance, formatted as a Javadoc comment.optionToHtml
(org.plumelib.options.Options.OptionInfo oi, int padding) Get the line of HTML describing one Option.output()
Get the final output of this doclet.void
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.
-
Constructor Details
-
OptionsDoclet
public OptionsDoclet()Create an OptionsDoclet.
-
-
Method Details
-
init
- Specified by:
init
in interfacejdk.javadoc.doclet.Doclet
-
getName
- Specified by:
getName
in interfacejdk.javadoc.doclet.Doclet
-
getSupportedOptions
- Specified by:
getSupportedOptions
in interfacejdk.javadoc.doclet.Doclet
-
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
-
write
Write the output of this doclet to the correct file.- Throws:
Exception
- if there is trouble
-
output
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:
Exception
- if there is trouble
-
processJavadoc
public void processJavadoc()Adds Javadoc info to each option inoptions.getOptions()
. -
optionsToHtml
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
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
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
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
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
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
-