RFR: JDK-8272945: Use snippets in java.compiler documentation

[Alan Bateman]

On Fri, 3 Dec 2021 00:26:10 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a patch to use snippets in the `java.compiler` documentation, instead of a mix of raw HTML and/or `{@code ...}`.  The change is just about the presentation of the code fragments; there are no changes to the normative specifications for the module.
> 
> One of the examples went to extraordinary lengths to include the character sequence `*/` within the example. That example has been replaced by an external snippet in a separate source file, which does not have any restriction on the use of `*/`. However, it does require that the file be excluded from standard compilation, and that is done by setting `EXCLUDES`, once for the "interim" compiler, and once again for the "product" compiler.    Going forward, a better solution might be to modify the `SetupJavaCompilation` macro to ignore all directories whose name is not a valid Java identifier (or, if easier, contains a `-`, such as `doc-files` or `snippet-files`.)

src/java.compiler/share/classes/javax/tools/JavaCompiler.java line 189:

> 187:  *     source code stored in a string:
> 188:  *
> 189:  *     {@snippet id=fileObject class=JavaSourceFromString }

JEP 413 uses the "file" attribute for external snippets, so using "class" here is new (to me anyway). Maybe the JEP should include an example that uses it.

Is this the first use of an external snippet in the src tree? I suspect files in the snippet-files directory will need a copyright header (downstream builders will report issues on this). It's not clear to me how that works if @replace region replacement="" isn't the first line of the external file.

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

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