Musings on 8232447: The javadoc parser ends the first sentence of a comment too soon

[Pavel Rappo]

> On 14 May 2020, at 22:22, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> On 5/14/20 1:12 PM, Pavel Rappo wrote:
>>> On 14 May 2020, at 20:46, Jonathan Gibbons <jonathan.gibbons at oracle.com>
>>>  wrote:
>>> 
>>> OK, but I'm still wondering why it is better to use a block tag for `@summary` compared to an inline tag
>>> 
>> Nested markup.
>> 
>> 
> If I'm understanding what you mean correctly, the problems with nested markup are the same for both inline and block tags.

Let me explain what I mean in detail to avoid further misunderstanding. When I described that idea of making {@summary} a bimodal tag I thought that there was a significant difference between inline tags and block tags. Namely, that block tags *could* have nested markup (HTML and Standard Doclet tags), whereas inline tags couldn't. I guess, I formed that impression by eyeballing myriads of doc comments over the years, rather than carefully reading relevant parts of "Documentation Comment Specification for the Standard Doclet". So I thought that, for example, the below snippet was impossible by design

    /**
     * {@summary Returns {@code true} if this module has <em>opened</em> a package to at
     * least the given module.}

whereas this was

    /** 
     * @summary Returns {@code true} if this module has <em>opened</em> a package to at
     * least the given module.

I thought that an author of a doc comment had to choose between reliable parsing and having their markup. However, that comment of yours

> the problems with nested markup are the same for both inline and block tags

made me re-read the relevant parts of the specification and realize that this is not the case. It is a de facto behavior, rather than a de jure standard.

Earlier in this thread, Roger said:

> IMHO the first sentence should be short and to the point and not include markup or
extra explainatory phrases (such as e.g.).

Yet, people do use markup in the first sentences. OpenJDK uses markup in the first sentences. `java.base` has hundreds [^1] of occurrences of it. I personally find that judicious use of *light* markup can assist in reading the resulting output. So this all stems from me trying to find a way to achieve that while preserving the benefits of the inline version of {@summary}.

-Pavel

[^1]: According to my quick and dirty regex-based search "/\*\*\s*\*.+<\w+>.*$"