Class OptionsDoclet

  • All Implemented Interfaces:
    jdk.javadoc.doclet.Doclet

    public class OptionsDoclet
    extends java.lang.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:
    Option, Options, OptionGroup, Unpublicized
    • Nested Class Summary

      • Nested classes/interfaces inherited from interface jdk.javadoc.doclet.Doclet

        jdk.javadoc.doclet.Doclet.Option
    • Constructor Summary

      Constructors 
      Constructor Description
      OptionsDoclet()
      Create an OptionsDoclet.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static java.lang.String docCommentToHtml​(com.sun.source.doctree.DocCommentTree docCommentTree)
      Replace the @link tags and block @see tags in a Javadoc comment with HTML.
      static @BinaryName java.lang.String getBinaryName​(javax.lang.model.element.TypeElement te)
      Returns the binary name of the given type.
      boolean getFormatJavadoc()
      Returns true if the output format is Javadoc, false if the output format is HTML.
      java.lang.String getName()  
      java.util.Set<? extends jdk.javadoc.doclet.Doclet.Option> getSupportedOptions()  
      javax.lang.model.SourceVersion getSupportedSourceVersion()  
      boolean getUseSingleDash()
      Return true if using a single dash (as opposed to a double dash) for command-line options.
      void init​(java.util.Locale locale, jdk.javadoc.doclet.Reporter reporter)  
      static boolean isTypeElement​(javax.lang.model.element.Element element)
      Returns true if the given element kind is a type, i.e., a class, enum, interface, or annotation type.
      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.
      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​(org.plumelib.options.Options.OptionInfo oi, int padding)
      Get the line of HTML describing one Option.
      java.lang.String output()
      Get the final output of this doclet.
      void processJavadoc()
      Adds Javadoc info to each option in options.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.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • OptionsDoclet

        public OptionsDoclet()
        Create an OptionsDoclet.
    • Method Detail

      • init

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

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

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

        public javax.lang.model.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
      • optionLength

        public 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. 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
      • write

        public void write()
                   throws java.lang.Exception
        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
        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()
        Adds Javadoc info to each option in options.getOptions().
      • optionsToHtml

        public java.lang.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 java.lang.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 java.lang.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 java.lang.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​(javax.lang.model.element.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 java.lang.String getBinaryName​(javax.lang.model.element.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