public class OptionsDoclet
extends java.lang.Object
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:
<!-- 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
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.
-outfile
is used, in which case, the file
is written in this directory.
-docfile
option is used, and
may not be used at the same time as the -outfile
option.
-docfile
option) using appropriate
indentation. Inline @link
and @see
tags in the Javadoc input are left
untouched.
@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.
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.
Option
,
Options
,
OptionGroup
,
Unpublicized
Modifier and Type | Field and Description |
---|---|
private @Nullable java.io.File |
docFile
The file into which options documentation is inserted.
|
private java.lang.String |
endDelim
Marker for end of options documentation.
|
private boolean |
formatJavadoc
If true, then output format is Javadoc.
|
private boolean |
includeClassDoc
If true, then include the class's main Javadoc comment.
|
private boolean |
inPlace
If true, then edit docFile in place (and docFile is non-null).
|
private static java.lang.String |
lineSep
The system-specific line separator.
|
private static java.lang.String |
LIST_HELP
Help message about options that can be specified multiple times.
|
private Options |
options
The command-line options.
|
private @Nullable java.io.File |
outFile
Destination for output.
|
private com.sun.javadoc.RootDoc |
root
The document root.
|
private java.lang.String |
startDelim
Marker for start of options documentation.
|
private static java.lang.String |
USAGE
How to use the Options doclet.
|
Constructor and Description |
---|
OptionsDoclet(com.sun.javadoc.RootDoc root,
Options options)
Create an OptionsDoclet that documents the given options.
|
Modifier and Type | Method and Description |
---|---|
boolean |
getFormatJavadoc()
Returns true if the output format is Javadoc, false if the output format is HTML.
|
boolean |
getUseSingleDash()
Return true if using a single dash (as opposed to a double dash) for command-line options.
|
static java.lang.String |
javadocToHtml(com.sun.javadoc.Doc doc)
Replace the @link tags and block @see tags in a Javadoc comment with HTML.
|
private static boolean |
needsInstantiation(java.lang.Class<?> clazz)
Determine if a class needs to be instantiated in order to work properly with
Options . |
private java.lang.String |
newDocFileText()
Get the result of inserting the options documentation into the docfile.
|
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.
|
private java.lang.String |
optionListToHtml(java.util.List<Options.OptionInfo> optList,
int padding,
int firstLinePadding,
int refillWidth)
Get the HTML describing many options, formatted as an HTML list.
|
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(Options.OptionInfo oi,
int padding)
Get the line of HTML describing one Option.
|
java.lang.String |
output()
Get the final output of this doclet.
|
private void |
processEnumJavadoc(Options.OptionInfo oi)
Initializes
Options.OptionInfo.enumJdoc for the given OptionInfo : creates a
mapping from enum constants to their Javadoc |
void |
processJavadoc()
Adds Javadoc info to each option in
options.getOptions() . |
private java.lang.String |
refill(java.lang.String in,
int padding,
int firstLinePadding,
int refillWidth)
Refill the string so that each line is
refillWidth characters long. |
void |
setFormatJavadoc(boolean val)
Supply true to set the output format to Javadoc, false to set the output format to HTML.
|
void |
setOptions(java.lang.String[][] options)
Set the underlying Options instance for this class based on command-line arguments given by
RootDoc.options().
|
void |
setUseSingleDash(boolean val)
|
static boolean |
start(com.sun.javadoc.RootDoc root)
Entry point for the doclet.
|
static boolean |
validOptions(java.lang.String[][] options,
com.sun.javadoc.DocErrorReporter reporter)
Tests the validity of command-line arguments passed to this doclet.
|
void |
write()
Write the output of this doclet to the correct file.
|
private static java.lang.String lineSep
private static final java.lang.String USAGE
private static final java.lang.String LIST_HELP
private java.lang.String startDelim
private java.lang.String endDelim
private @Nullable java.io.File docFile
private @Nullable java.io.File outFile
private boolean inPlace
private boolean formatJavadoc
private boolean includeClassDoc
private com.sun.javadoc.RootDoc root
private Options options
public OptionsDoclet(com.sun.javadoc.RootDoc root, Options options)
root
- the document rootoptions
- the command-line optionspublic static boolean start(com.sun.javadoc.RootDoc root)
root
- the root documentpublic static int optionLength(java.lang.String option)
option
- the command-line optionpublic static boolean validOptions(java.lang.String[][] options, com.sun.javadoc.DocErrorReporter reporter)
Also sets fields from the command-line arguments.
options
- the command-line options to be checked: an array of 1- or 2-element arrays,
where the length depends on optionLength(java.lang.String)
applied to the first elementreporter
- where to report errorspublic void setOptions(java.lang.String[][] options)
options
- the command-line options to parse: a list of 1- or 2-element arraysprivate static boolean needsInstantiation(java.lang.Class<?> clazz)
Options
.clazz
- the class whose values will be created by command-line argumentspublic void write() throws java.lang.Exception
java.lang.Exception
- if there is troublepublic java.lang.String output() throws java.lang.Exception
java.lang.Exception
- if there is trouble@RequiresNonNull(value="docFile") private java.lang.String newDocFileText() throws java.lang.Exception
java.lang.Exception
- if there is trouble reading filespublic void processJavadoc()
options.getOptions()
.private void processEnumJavadoc(Options.OptionInfo oi)
Options.OptionInfo.enumJdoc
for the given OptionInfo
: creates a
mapping from enum constants to their Javadocoi
- the enum option whose Javadoc to readpublic java.lang.String optionsToHtml(int refillWidth)
refillWidth
- the number of columns to fit the text into, by breaking linespublic java.lang.String optionsToJavadoc(int padding, int refillWidth)
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 linesprivate java.lang.String optionListToHtml(java.util.List<Options.OptionInfo> optList, int padding, int firstLinePadding, int refillWidth)
optList
- the options to documentpadding
- the number of leading spaces to add before each line of HTML output, except the
first onefirstLinePadding
- the number of leading spaces to add before the first line of HTML
outputrefillWidth
- the number of columns to fit the text into, by breaking linesprivate java.lang.String refill(java.lang.String in, int padding, int firstLinePadding, int refillWidth)
refillWidth
characters long.in
- the string to refillpadding
- each line, other than the first, starts with this many spacesfirstLinePadding
- the first line starts with this many spacesrefillWidth
- the maximum width of each line in the output, including the paddingrefillWidth
characters appear between any two
end-of-line character sequencespublic java.lang.String optionToHtml(Options.OptionInfo oi, int padding)
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)public static java.lang.String javadocToHtml(com.sun.javadoc.Doc doc)
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.
doc
- a Javadoc comment to convert to HTMLpublic boolean getFormatJavadoc()
public void setFormatJavadoc(boolean val)
val
- true to set the output format to Javadoc, false to set the output format to HTMLpublic boolean getUseSingleDash()
public void setUseSingleDash(boolean val)
val
- whether to use a single dash (as opposed to a double dash) for command-line options