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

[Jonathan Gibbons]

On Wed, 24 Jan 2024 16:24:25 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - fix @since tags
>>  - fix copyright year
>
> 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.

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

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