On Tue, 30 Jan 2024 23:07:46 GMT, Jonathan Gibbons <j...@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
