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

[Pavel Rappo]

On Mon, 29 Nov 2021 13:55:39 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> The primary purpose of this change is to make it easier to spot invalid snippets in generated documentation. 
>> 
>> This adds a new `Content invalidTagOutput(String summary, Optional<String> detail)` method to the `TagletWriter` class that returns HTML to display the summary and optionally a detail message. The method is only used for snippet tags for now, but is generic and could be used for other invalid tags in the future. 
>> 
>> If the `detail` argument is empty or contains a blank string, a `<span>` element is returned containing the `summary` argument. If a detail argument is provided, a HTML5 `<details>` element is returned containing a `<summary>` element with the `summary` argument and a `<pre>` element containing the `details` argument. In both cases the returned element is styled with a thin border and a light red background.
>> 
>> In its current use the `detail` argument is always provided by the message of the `ParseException` or `BadSnippetException` that was thrown and caught. 
>> 
>> Example output is available here: http://cr.openjdk.java.net/~hannesw/8276964/api.01/snippet_errormessages/A.html
>> 
>> I added output checks to some but not all of the negative tests. In addition I slightly reformatted `TestSnippetTag.java` to add indentation to some previously unindeted text blocks.
>
> 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?

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

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