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...)
. You can set the Option.noDocDefault()
field to true
to omit the default value string
from the generated documentation for an option.
Omitting the generated default value string is useful for options that have system-dependent
defaults. Reporting the system-dependent default is appropriate for usage messages that are
generated at run time, but are not appropriate for documentation that is meant to apply to all
users. Consider the following @
Option
-annotated field:
@Option(value="<timezone> Set the time zone") public static String timezone = TimeZone.getDefault().getID();The default value for
timezone
depends on the system's timezone setting. HTML
documentation of this option generated in Chicago would not apply to a user in New York. To work
around this problem, the default value should be hidden; instead the Javadoc for this field
should indicate the default in the main Javadoc comment, and the Option
annotation should
include noDocDefault=true
. For example:
/** * <other stuff...> This option defaults to the system timezone. */ @Option(value="<timezone> Set the timezone", noDocDefault=true) public static String timezone = TimeZone.getDefault().getID();This keeps the documentation system-agnostic.
Caveats
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 |
private java.lang.String |
endDelim |
private static java.lang.String |
eol |
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 |
LIST_HELP |
private Options |
options |
private @Nullable java.io.File |
outFile |
private com.sun.javadoc.RootDoc |
root |
private java.lang.String |
startDelim |
private static java.lang.String |
USAGE |
Constructor and Description |
---|
OptionsDoclet(com.sun.javadoc.RootDoc root,
Options 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()
|
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 eol
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)
public 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