RFR: 8298405: Implement JEP 467: Markdown Documentation Comments [v69]

[Jonathan Gibbons]

On Thu, 16 May 2024 15:03:26 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> If you are concerned with it being a lint warning rather than a **doc**lint warning, then it's a technicality: doclint sees less than lint sees, and sadly not enough for that check. Thus, that check was put in `lint.

To clarify that a bit ...

There's a subtle difference between _documentation comments_ and _documentation comments as used with the standard doclet_.  From the beginning, documentation comments have been those enclosed in `/**...*/` but there has never been a formal specification that the only content is that accepted by the standard doclet. Indeed, over the years, there have been various doclets, not all from Sun/Oracle, and not all accepting the content syntax used by the standard doclet.  This practice continues with the introduction of `///` comments.

So, there are actually two issues conflated in this work:
1. introducing the use of `///` for documentation comments
2. introducing the use of Markdown for some comments

They go together because it would be silly/confusing to introduce `///` comments by themselves, and figuring out what to do with them until the use of Markdown was introduced. Arguably, the first bullet by itself could have been a Preview feature, but it probably falls below any appropriate threshold.  You might also note that `Elements.getDocComment` and friends say nothing about the syntactic form of the content of any doc comment after the lexical wrappings have been removed.  In particular, words like HTML and Markdown do not appear in the specs for these methods. This is intentional and means that a different doclet could interpret the content of the doc comment in any way that it chooses.

Back to this thread, and `-Xlint` vs `-Xdoclint`:

`doclint` is specifically about issues within the content of doc comments as defined in the `JavaDoc Documentation Comment Specification for the Standard Docket` and  interpreted by the standard doclet.

`dangling-doc-comments` is not specific to comments seen by the standard doclet. It applies to all doc comments, whatever the form of their content. As such, it is a `javac` lexical check, and belongs in `-Xlint`.

-------------

PR Comment: https://git.openjdk.org/jdk/pull/16388#issuecomment-2115724002