RFR: 8266666: Implementation for snippets

[Jonathan Gibbons]

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.

The overall structure looks generally good. Nice work.

That being said, I note the following ...

* All new top-level classes should have a reasonable documention comment, including where appropriate the standard boilerplate (i.e. not on public API classes and interfaces)

     *  <p><b>This is NOT part of any supported API.
     *  If you write code that depends on this, you do so at your own risk.
     *  This code and its internal interfaces are subject to change or
     *  deletion without notice.</b>

* All new non-private methods should have a reasonable documentation comment

* There's more than a typical number of chatty comments and/or fixme comments and/or code that needs to be uncommented.   I'll do a separate review pass to note some of those examples.

* Please work with @hns to determine the proposed CSS style(s) to be used, and not just the interim placeholder `sandybrown`.  The color should be compatible with the existing color palette.  Ideally, at the same time, in either this changes or a sibling changes, we should change the style of a default `<pre>{code}` block to be similar with respect to the basic display characteristics.

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

Changes requested by jjg (Reviewer).

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