> On 14 May 2020, at 22:22, Jonathan Gibbons <[email protected]>
> wrote:
>
> On 5/14/20 1:12 PM, Pavel Rappo wrote:
>>> On 14 May 2020, at 20:46, Jonathan Gibbons <[email protected]>
>>> 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+>.*$"
