RFR: 8266666: Implementation for snippets [v22]

[Hannes Wallnöfer]

On Thu, 9 Sep 2021 13:40:20 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.
>
> Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 31 commits:
> 
>  - Clean up code
>    
>    Removes stale FIXMEs, TODOs and comments; downgrades FIXMEs to TODOs where possible; wraps overly long lines.
>  - Merge branch 'master' into 8266666
>  - Merge branch 'master' into 8266666
>  - Refactor SnippetTaglet
>    
>    Improves code style; reformats.
>  - Improve snippet attributes parsing
>    
>    DocCommentParser now recognizes end-of-input better. To test that in testBadTagSyntax, the ToolBox.writeJavaFiles approach was used instead that of ClassBuilder.write. This is because ClassBuilder muddled doc comments with extra formatting such as trailing newline. So from within `ClassBuilder.MethodBuilder.setComments(java.lang.String...)` one couldn't make an immediate end-of-input: there was always `\n` appended to the comment.
>    
>    Also reformatted testBadTagSyntax for ease of comparing input and expected error output.
>  - Merge branch 'master' into 8266666
>  - Be more specific when testing for syntax errors
>    
>    This commit (i) improves tests for bad syntax, (ii) re-formats testBadTagSyntax for ease of commenting out individual testcases, and (iii) removes commented out testcases that are unfeasible.
>  - Merge branch 'master' into 8266666
>  - Merge branch 'master' into 8266666
>  - Clean up tag parsing
>    
>    Removes two methods from an older implementation where HTML and javadoc tag attributes were modelled by different DocTree subtypes. Moves the `tagAttrs` method to TagParser responsible for parsing `@snippet` because `:` attribute terminator is specific to `@snippet`. Makes parser stop on `:`. Removes chatty discussion comments from code as suggested by Jonathan Gibbons.
>  - ... and 21 more: https://git.openjdk.java.net/jdk/compare/f6cc1732...a2173165

I went through the changes again, they mostly look good. There are a few areas (mostly handling of tags and styled text) where I still want to do more exploring in order to better understand the code.

I left inline comments for minor issues/questions I encountered.

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

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