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

[Pavel Rappo]

On Fri, 26 Nov 2021 16:40:09 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.

> The primary purpose of this change is to make it easier to spot invalid snippets in generated documentation.
> 

> In its current use the detail argument is always provided by the message of the ParseException or BadSnippetException that was thrown and caught.
> 

What "details" should provide depends on the target audience. Who is the target audience of this feature? Is it the author who composes the doc comment in source? Is it the tool user who builds the documentation from this comment? Or is it the reader who reads only the resulting documentation?

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

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