Summary

API support for the @snippet tag.

Problem

JEP 413 introduces an @snippet tag for JavaDoc's Standard Doclet, to simplify the inclusion of example source code in API documentation. In the Compiler Tree API, the package com.sun.source.doctree provides interfaces to represent documentation comments as abstract syntax trees (AST). This API needs to be updated to provide support for the new tag.

Solution

A new interface com.sun.source.doctree.SnippetTree is introduced, to provide basic support for representing an instance of an @snippet tag.

Corresponding updates are made to add new methods to DocTreeVisitor and its subclasses.

The interface is deliberately simple and open-ended, providing access to the attributes and any inline content in the tag, so as not to restrict any future evolution of the tag.

Support is only provided for the representation of the tag itself; no support is provided at this time for the parsed content of the snippet body, which is used within the Standard Doclet to create the output that appears in generated documentation.

A new command-line option --snippet-path <path> for the Standard Doclet is added, to allow a user to specify a path to search for the files for external snippets. Matching that, a new member SNIPPET_PATH is added to javax.tools.DocumentationTool.Location for use when invoking JavaDoc via the javax.tools.DocumentationTool API.

Specification

The changes to the specification are attached.

The command-line help for the new option is listed under the options for the Standard Doclet, and is:

--snippet-path <path>
              The path for external snippets