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

[Hannes Wallnöfer]

On Mon, 29 Nov 2021 13:55:39 GMT, Hannes Wallnöfer <hann...@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

I did a few quick experiments to see what the output looks like for other tags 
(BTW there is not a lot of test coverage for this, `TestSearch.java` testing 
invalid `{@index}` tags is one of two I found.)

1. Just passing the doc tree string representation as summary and empty detail:
        <img width="718" alt="invalid-tag-1" 
src="https://user-images.githubusercontent.com/15975/144025264-c0b399f2-e623-4b7b-85ad-afbd142ec52f.png";>

2. Passing "Invalid tag" as summary and the doc tree string representation as 
detail (collapsed/expanded):
        <img width="737" alt="invalid-tag-2" 
src="https://user-images.githubusercontent.com/15975/144025395-06d81566-fa60-415e-821a-353712cb5128.png";>

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

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