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

[Hannes Wallnöfer]

On Mon, 29 Nov 2021 14:20:01 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Hannes Wallnöfer has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Normalize newlines on detail message
>
> 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.

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

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