Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8266669

Implementation for snippets

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 18
    • Component/s: tools
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      new feature
    • Scope:
      SE

      Description

      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

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              prappo Pavel Rappo
              Reporter:
              jjg Jonathan Gibbons
              Reviewed By:
              Pavel Rappo
              Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: