1 Javadoc

The javadoc tool is a program that reads a collection of source files into an internal form.

The structure is: (source-files)->[javadoc-tool:doclet]->(generated files).

The Javadoc doclet is like a pluggable back end that analyzes this internal form with some goal in mind. It can generate HTML, MIF, or XML files, depending on the doclet.

The content of the generated files is specific to the doclet. The standard doclet generates HTML documentation, but a different doclet, for example, could generate a report of misspelled words or grammatical errors.

If you specify a doclet other than the standard doclet, then the descriptions in this guide might not apply to the operation of that doclet or the files (if any) that are generated.

To use the javadoc tool, you must:

  • Write source code, containing documentation comments. Documentation comments are formatted in HTML and are interspersed with the javadoc tool.

  • Run the javadoc tool. You need to specify a doclet to analyze the documentation comments and any other special tags. However, if you don’t specify any doclet, by default, the Standard Doclet is included. You specify a number of command-line options, some of which are directed at the javadoc tool itself, and some of which are specific to the selected doclet. The command-line help shows and distinguishes the options for the tool that apply to the currently selected doclet. When the standard doclet is used, the output generated by the standard doclet consists of a series of HTML pages. If you specify a different doclet, then the operation of that doclet and what files (if any) are generated may or may not be equivalent to the standard doclet described in this guide.

Javadoc Features

Javadoc features include the following: Javadoc search, support for generating HTML5 output, support for documentation comments in module systems, and simplified Doclet API.

Search

The javadoc tool runs the doclet that may generate output. The standard doclet generates output that lets you search the generated documentation. A search box is available on the generated APIs and provides the following:

  • You can search for elements and additional key phrases defined in the API

  • Results, including results that exactly match the entered characters followed by results that contains the entered characters anywhere in the string. Multiple results are displayed as simple scrolling lists below the search box. Results are categorized as follows, for easier classification and appropriate user selection:

    • Modules

    • Packages

    • Types

    • Members

    • Search Tags

    Multiple results with different program element names are displayed if the search term or a phrase is inherited using the @inheritDoc tag.

  • Page redirection based on user selection.

You can search for the following:

  • Declared names of modules, packages, types, and members: Because methods can be overloaded, the simple names of method parameter types are also indexed and can be searched for. The method parameter names can’t be indexed.

  • A search term or a phrase indexed using a new inline tag, @index: Other inline tags cannot be nested inside @index. You can only search a phrase or search term marked with @index within a declaration's javadoc comment. For example, the ___domain-specific term ulps is used throughout the java.lang.Math class, but doesn't appear in any class or method declaration names. To help users of the Math API, the API designer could tag various occurrences of ulps in a class-level javadoc comment or a method-level javadoc comment. Tagging is achieved using {@index ulps}. The term ulps is indexed by the javadoc tool.

Module System

The javadoc tool supports documentation comments in module declarations. Some Javadoc command-line options enable you to specify the set of modules to document and generate a new summary page for any modules being documented. It has new command-line options to configure the set of modules to be documented and generates a new summary page for any modules being documented. See javadoc Doclet Options.

HTML 5 Support

You can generated HTML5 output. To get fully-compliant HTML5 output, ensure that any HTML content provided in documentation comments are compliant with HTML5.

Simplified Doclet API

The Doclet API uses powerful APIs that can better represent all the language features. See Standard Doclet Options.