On Wed, 24 Jan 2024 16:24:25 GMT, Pavel Rappo <pra...@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
