API support for the
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.
A new interface
com.sun.source.doctree.SnippetTree is introduced,
to provide basic support for representing an instance of an
Corresponding updates are made to add new methods to
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
for use when invoking JavaDoc via the
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
- csr of
JDK-8266666 Implementation for snippets
- relates to
JDK-8273175 Add @since tags to the DocTree.Kind enum constants