RFR: 8266666: Implementation for snippets

[Hannes Wallnöfer]

On Thu, 15 Jul 2021 14:13:16 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.

Overall the code looks good! 

A few comments inline. I'll have a look at the stylesheet changes next.

src/jdk.compiler/share/classes/com/sun/source/doctree/SnippetTree.java line 46:

> 44:  * </pre>
> 45:  *
> 46:  * @since 17

Should be `@since 18` (a few other instances)

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SnippetTaglet.java line 108:

> 106:         }
> 107: 
> 108:         String r = null;

I would prefer if variables such as this that are used farther than a few lines from their definition had more meaningful names.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/parser/Parser.java line 275:

> 273:                         throw new ParseException("Unexpected attributes", t.lineSourceOffset + t.markupLineOffset + t.nameLineOffset);
> 274:                     }
> 275:                     actions.add(new Bookmark(region.value(), text.subText(t.start(), t.end() - 1)));

This method is a bit hard on the eyes and runs quite wide. Maybe add a few more line breaks on those very long lines?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/text/AnnotatedText.java line 46:

> 44:  * rich text style.
> 45:  */
> 46: public class AnnotatedText<S> {

As far as I can see, this class is always parameterized with Style. Do you foresee any other types of annotations being used with it?

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

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