RFR: JDK-8276964: Better indicate a snippet that could not be processed [v2]

[Jonathan Gibbons]

On Mon, 29 Nov 2021 15:04:30 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java line 540:
>> 
>>> 538:             return HtmlTree.SPAN(HtmlStyle.invalidTag, Text.of(summary));
>>> 539:         }
>>> 540:         return new HtmlTree(TagName.DETAILS).addStyle(HtmlStyle.invalidTag)
>> 
>> This 3-state detail bothers me:
>> 
>>   1. The detail is absent (i.e. the optional is empty)
>>   2. The detail is a blank
>>   3. The detail is non-blank
>> 
>> If we care about a blank detail (i.e. an error description that consists only of whitespace), then why treat it like an absent detail and omit it from the documentation? If we don't care about a blank detail, then why wrap it in an `Optional` when a blank string would do?
>
> It's not meant to be "part of the method spec", it's just that it's silly to display a summary/detail box unless you have something to show in the details. Think of it as a very trivial application of Postel's law. BTW, this kind of flexibility in choosing the appropriate container is one of the things that led me to choose `Optional` argument instead of overloaded methods. It just looks nicer to my eyes.

I'd be inclined for either `detail` to be `Optional<Content>` or for there to be an overload that allows `Optional<String>` that calls the sibling with `Optional<Content>`

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

PR: https://git.openjdk.java.net/jdk/pull/6579