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

Support Markdown in the standard doclet

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P3
    • 23
    • tools
    • None
    • source, binary, behavioral
    • minimal
    • This is a new feature, for a new style of documentation comment with lines beginning with `///`
    • File or wire format
    • JDK

    Description

      Summary

      Support Markdown in documentation comments processed by javadoc's Standard Doclet.

      Problem

      While HTML has been the standard for rich text in documentation comments since forever, it is a cumbersome format to read and edit in the source code, Markdown is becoming a de-facto standard for "simple" rich text, as typically found in documentation comments. It would be good to be able to support Markdown in documentation comments.

      Solution

      A new style of documentation comment consisting of a series of consecutive lines each beginning with /// is recognized as being a Markdown comment.

      Within a Markdown comment, the following applies:

      • The overall syntax for the comment remains that of a description, optionally followed by block tags.

      • In the description, and in any tags that can contain rich text, the syntax is that of CommonMark interspersed with standard and user-defined inline tags.

      • Inline and block tags are parsed and processed individually, and then treated as opaque objects in the enclosing context. (The intent and net effect is that you cannot use syntactic Markdown forms that partially overlap with any tag.)

      • The content of Markdown code spans and code blocks is treated as literal text, and so inline and block tags are not recognized within code spans and code blocks.

      • Reference links are extended to allow simple references to program elements.

      • There is no special handling for &, to introduce an entity, or < to introduce an HTML start or end element. Entities and HTML elements may still appear, but will be treated as part of the Markdown code, and processed as such.

      Disabling /// comments

      An investigation of publicly available source code indicates that some developers already use /// in ways that may be incompatible with the new use for documentation comments. For those situations where it may be undesirable to modify existing comments, a new option for both javac and javadoc will be provided, to disable recognition of comments beginning with /// as documentation comments.

      Specification

      The changes to the API specifications and to the Document Comment Specification for the Standard Doclet are attached. (Latest version: 07) The specifications can also be seen here:

      Note: the changes to the Document Comment Specification for the Standard Doclet primarily consist of including relevant parts of the associated JEP into this document, along with some minor cosmetic changes. There should be no significant differences between the specification detailed here and in the JEP.

      Disabling /// comments

      The following is added to the javac man page:

      +<a id="option-disable-line-doc-comments">`--disable-line-doc-comments`</a>
      +:   Disables support for documentation comments with lines beginning ///.
      +
       <a id="option-Djava.endorsed.dirs">`-Djava.endorsed.dirs=`*dirs*</a>

      A corresponding entry is added to the list of "pass-through" options for javac on the javadoc man page:

       * <span id="option-class-path">`--class-path`, `-classpath`, or `-cp`</span>
      +* <span id="option-disable-line-doc-comments">`--disable-line-doc-comments`</span>
       * <span id="option-enable-preview">`--enable-preview`</span>

      java.compiler/javax.lang.model.util.Elements

      javax.lang.model.util.Elements contains a method getDocComment(Element) that defines the form of a documentation comment. This method is updated to include the new /// form. A new method is added to determine the kind of documentation comment used for an element. These changes are described separately, in JDK-8329632.

      Attachments

        1. apidiff.02.zip
          174 kB
        2. apidiff.03.zip
          175 kB
        3. apidiff.04.zip
          151 kB
        4. apidiff.05.zip
          151 kB
        5. apidiff.06.zip
          169 kB
        6. apidiff.07.zip
          169 kB
        7. specdiff.00.zip
          955 kB
        8. specdiff-api.02.zip
          1012 kB
        9. specdiff-api.03.zip
          1020 kB
        10. specdiff-api.04.zip
          1017 kB
        11. specdiff-api.05.zip
          1017 kB
        12. specdiff-api.06.zip
          994 kB
        13. specdiff-api.07.zip
          994 kB
        14. specdiff-dcs.02.zip
          79 kB
        15. specdiff-dcs.03.zip
          80 kB
        16. specdiff-dcs.04.zip
          90 kB
        17. specdiff-dcs.05.zip
          90 kB
        18. specdiff-dcs.06.zip
          89 kB
        19. specdiff-dcs.07.zip
          90 kB
        20. specdiff-man.04.zip
          68 kB
        21. specdiff-man.05.zip
          68 kB
        22. specdiff-man.06.zip
          69 kB
        23. specdiff-man.07.zip
          69 kB

        Issue Links

          Activity

            People

              jjg Jonathan Gibbons
              jjg Jonathan Gibbons
              Pavel Rappo
              Votes:
              0 Vote for this issue
              Watchers:
              7 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: