RFR: JDK-8298405: Support Markdown in Documentation Comments [v16]

[Jonathan Gibbons]

On Tue, 30 Jan 2024 23:07:46 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java line 572:
>> 
>>> 570:                         }
>>> 571: 
>>> 572:                         case TEXT -> {
>> 
>> I haven't looked at `SentenceBreaker` in detail, but one thing that bothers me is that it sees a comment before that comment has been transformed. This means that `///` comments might not "feel" like Markdown to authors.
>
> First up: I do not understand your second sentence: _This means that /// comments might not "feel" like Markdown to authors._    Please rephrase or clarify that.
> 
> That aside, there's a big case of chickens and eggs here.  The API assumes that the first sentence is distinct from the rest of the description, so we cannot transform it at that early stage.  But generally, the first sentence is supposed to be reasonably simple text, and for cases where it is not, you can use the `summary` tag to circumvent any use of the sentence breaker.
> 
> Bottom line, I do not see any cause for concern at this time.

To add to that, regarding this:
> but one thing that bothers me is that it sees a comment before that comment has been transformed

I don't think we should support any transformations (i.e. custom extensions to Markdown) that would affect the detection of the end of the first sentence.  As of this review, the only custom extension is for enhanced links which simply infer link definitions for appropriate reference links.   If there is anything that is worth checking, it is the handling of any links, including reference links, in the first sentence.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1475229987