OptionsDoclet

java.lang.Object
- plume.OptionsDoclet

Deprecated.
Use org.plumelib.options.OptionsDoclet
```
@Deprecated
public class OptionsDoclet
extends java.lang.Object
```
Generates HTML documentation of command-line options. Works with the Options class.
Usage
This doclet is typically invoked with:
```
javadoc -quiet -doclet plume.OptionsDoclet [doclet options] [java files]
```
Doclet Options
The following doclet options are supported:
- -docfile file When specified, the output of this doclet is the result of replacing everything between the two lines
```

```
  and
```

```
  in file with the options documentation. This can be used for inserting option documentation into an existing manual. The existing docfile is not modified; output goes to the -outfile argument, or to standard out.
- -outfile file The destination for the output (the default is standard out). If both -outfile and -docfile are specified, they must be different. 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. Otherwise, this option is ignored.
- -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. This is useful for including option documentation inside Java source code. When this format is used with the -docfile option, the generated documentation is inserted between the lines
```
* 
```
    and
```
* 
```
    using the same 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. This is the default output format and does not need to be specified explicitly.
- -classdoc When specified, the output of this doclet includes the class documentation of the first class specified on the command-line.
- -singledash When specified, use_single_dash(true) is called on the underlying instance of Options used to generate documentation. See Options.use_single_dash(boolean).
Examples
To update the Javarifier HTML manual with option documentation run:
```
 javadoc -quiet -doclet plume.OptionsDoclet -i -docfile javarifier.html src/javarifier/Main.java
 
```
To update the class Javadoc for plume.Lookup with option documentation run:
```
 javadoc -quiet -doclet plume.OptionsDoclet -i -docfile Lookup.java -format javadoc Lookup.java
 
```
For a more extensive example, see file java/Makefile in plume-lib itself.
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...). The Option.noDocDefault() field in the @Option annotation can be set to true to omit the default value string from the generated documentation for that option.
Omitting the generated default value string is useful for options that have system-dependent defaults. Such options are not an issue for usage messages that are generated at runtime. However, system dependent defaults do pose a problem for static documentation, which is rarely regenerated and 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 a special default as follows.
```
 &#47;**
  * <other stuff...>  This option defaults to the system timezone.
  *&#47;
 &#64;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 includes unpublicized option groups but not @Unpublicized options. Option groups that contain only @Unpublicized options are not included in the output at all.
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 and Description

OptionsDoclet(com.sun.javadoc.RootDoc root, Options options)
Deprecated.

Constructors
Constructor and Description
`OptionsDoclet(com.sun.javadoc.RootDoc root, Options options)` Deprecated.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`getFormatJavadoc()` Deprecated.
`boolean`	`getUseSingleDash()` Deprecated.
`static java.lang.String`	`javadocToHtml(com.sun.javadoc.Doc doc)` Deprecated. Replace the @link tags and block @see tags in a Javadoc comment with sensible, non-hyperlinked HTML.
`static int`	`optionLength(java.lang.String option)` Deprecated. 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)` Deprecated. Get the HTML documentation for the underlying options instance.
`java.lang.String`	`optionsToJavadoc(int padding, int refillWidth)` Deprecated. Get the HTML documentation for the underlying options instance, formatted as a Javadoc comment.
`java.lang.String`	`optionToHtml(plume.Options.OptionInfo oi, int padding)` Deprecated. Get the line of HTML describing an Option.
`java.lang.String`	`output()` Deprecated. Get the final output of this doclet.
`void`	`processJavadoc()` Deprecated. Side-effects each option in `options.getOptions()`.
`void`	`setFormatJavadoc(boolean val)` Deprecated.
`void`	`setOptions(java.lang.String[][] options)` Deprecated. Set the options for this class based on command-line arguments given by RootDoc.options().
`void`	`setUseSingleDash(boolean val)` Deprecated.
`static boolean`	`start(com.sun.javadoc.RootDoc root)` Deprecated. Entry point for the doclet.
`static boolean`	`validOptions(java.lang.String[][] options, com.sun.javadoc.DocErrorReporter reporter)` Deprecated. Tests the validity of command-line arguments passed to this doclet.
`void`	`write()` Deprecated. Write the output of this doclet to the correct file.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - OptionsDoclet
```
public OptionsDoclet(com.sun.javadoc.RootDoc root,
                     Options options)
```
    Deprecated.
- Method Detail
  - start
```
public static boolean start(com.sun.javadoc.RootDoc root)
```
    Deprecated.
    
    Entry point for the doclet.
    
    Parameters:
    
    root - the root document
    
    Returns:
    
    true if processing completed without an error
  - optionLength
```
public static int optionLength(java.lang.String option)
```
    Deprecated.
    
    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
  - validOptions
```
public static boolean validOptions(java.lang.String[][] options,
                                   com.sun.javadoc.DocErrorReporter reporter)
```
    Deprecated.
    
    Tests the validity of command-line arguments passed to this doclet. Returns true if the option usage is valid, and false otherwise. This method is automatically invoked by Javadoc.
    
    Parameters:
    
    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 element
    
    reporter - where to report errors
    
    Returns:
    
    true iff the command-line options are valid
    
    See Also:
    
    Doclet overview
  - setOptions
```
public void setOptions(java.lang.String[][] options)
```
    Deprecated.
    
    Set the options for this class based on command-line arguments given by RootDoc.options().
    
    Parameters:
    
    options - the command-line options to parse: a list of 1- or 2-element arrays
  - write
```
public void write()
           throws java.lang.Exception
```
    Deprecated.
    
    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
```
    Deprecated.
    
    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()
```
    Deprecated.
    
    Side-effects each option in options.getOptions(). Adds Javadoc info to it.
  - optionsToHtml
```
public java.lang.String optionsToHtml(int refillWidth)
```
    Deprecated.
    
    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)
```
    Deprecated.
    
    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(plume.Options.OptionInfo oi,
                                     int padding)
```
    Deprecated.
    
    Get the line of HTML describing an Option.
    
    Parameters:
    
    oi - the option to describe
    
    padding - the number of spaces to add at the begginning of the detail line (after the line with the option itself)
    
    Returns:
    
    HTML describing oi
  - javadocToHtml
```
public static java.lang.String javadocToHtml(com.sun.javadoc.Doc doc)
```
    Deprecated.
    
    Replace the @link tags and block @see tags in a Javadoc comment with sensible, non-hyperlinked HTML. This keeps most of the information in the comment while still being presentable.
    This is only a temporary solution. Ideally, @link/@see tags would be converted to HTML links that point to actual documentation.
    
    Parameters:
    
    doc - a Javadoc comment to convert to HTML
    
    Returns:
    
    HTML version of doc
  - getFormatJavadoc
```
public boolean getFormatJavadoc()
```
    Deprecated.
  - setFormatJavadoc
```
public void setFormatJavadoc(boolean val)
```
    Deprecated.
  - getUseSingleDash
```
public boolean getUseSingleDash()
```
    Deprecated.
  - setUseSingleDash
```
public void setUseSingleDash(boolean val)
```
    Deprecated.

Class OptionsDoclet

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

OptionsDoclet

Method Detail

start

optionLength

validOptions

setOptions

write

output

processJavadoc

optionsToHtml

optionsToJavadoc

optionToHtml

javadocToHtml

getFormatJavadoc

setFormatJavadoc

getUseSingleDash

setUseSingleDash