Class OptionsDoclet

java.lang.Object
org.plumelib.options.OptionsDoclet
All Implemented Interfaces:
jdk.javadoc.doclet.Doclet

public class OptionsDoclet extends 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 the 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.
  • -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:
  • Constructor Details

    • OptionsDoclet

      public OptionsDoclet()
      Create an OptionsDoclet.
  • Method Details

    • init

      public void init(Locale locale, jdk.javadoc.doclet.Reporter reporter)
      Specified by:
      init in interface jdk.javadoc.doclet.Doclet
    • getName

      public String getName()
      Specified by:
      getName in interface jdk.javadoc.doclet.Doclet
    • getSupportedOptions

      public Set<? extends jdk.javadoc.doclet.Doclet.Option> getSupportedOptions()
      Specified by:
      getSupportedOptions in interface jdk.javadoc.doclet.Doclet
    • getSupportedSourceVersion

      public SourceVersion getSupportedSourceVersion()
      Specified by:
      getSupportedSourceVersion in interface jdk.javadoc.doclet.Doclet
    • run

      public boolean run(jdk.javadoc.doclet.DocletEnvironment denv)
      Specified by:
      run in interface jdk.javadoc.doclet.Doclet
    • write

      public void write() throws Exception
      Write the output of this doclet to the correct file.
      Throws:
      Exception - if there is trouble
    • output

      public String output() throws 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:
      Exception - if there is trouble
    • processJavadoc

      public void processJavadoc()
      Adds Javadoc info to each option in options.getOptions().
    • optionsToHtml

      public 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 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 String optionToHtml(org.plumelib.options.Options.OptionInfo oi, int padding)
      Get the line of HTML describing one 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
    • docCommentToHtml

      public static 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(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 String getBinaryName(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