RFR: 8308016: Use snippets in java.io package [v2]

[Tagir F. Valeev]

On Fri, 12 May 2023 19:02:46 GMT, Brian Burkhalter <bpb at openjdk.org> wrote:

>> Replace `<pre>{@code ...}</pre>` patterns and the like with `{@snippet lang=java : ...}`.
>
> Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:
> 
>   8308016: Remove ellipses ("...") from snippets

src/java.base/share/classes/java/io/FilePermission.java line 1033:

> 1031:      *
> 1032:      * {@snippet lang=java :
> 1033:      *     "/tmp/scratch/foo", "read,write",

This doesn't look like a valid Java code. This is not even a well-formed expression. I'm not sure whether there are any standard requirements about this (the spec is vague here), but IntelliJ IDEA assumes that the Java snippet is a member, a statement, or an expression. It's likely that parse error will be displayed here in the IDE.

src/java.base/share/classes/java/io/ObjectStreamField.java line 179:

> 177:      * Returns character encoding of field type.  The encoding is as follows:
> 178:      * {@snippet lang=java :
> 179:      *     B            byte

This is even less Java code. I don't think that snippet is appropriate here.

src/java.base/share/classes/java/io/RandomAccessFile.java line 904:

> 902:      * {@code b7}, and {@code b8,} where:
> 903:      * {@snippet lang=java :
> 904:      *         0 <= b1, b2, b3, b4, b5, b6, b7, b8 <= 255,

Same: this is not Java language syntax. Code or pre tags are fine here, they are not deprecated.

src/java.base/share/classes/java/io/StreamTokenizer.java line 394:

> 392:      * characters:
> 393:      * {@snippet lang=java :
> 394:      *         0 1 2 3 4 5 6 7 8 9 . -

But Java as well

src/java.base/share/classes/java/io/StreamTokenizer.java line 774:

> 772:      *
> 773:      * {@snippet lang=java :
> 774:      *         Token['a'], line 10

Also not Java.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/13957#discussion_r1193078718
PR Review Comment: https://git.openjdk.org/jdk/pull/13957#discussion_r1193078810
PR Review Comment: https://git.openjdk.org/jdk/pull/13957#discussion_r1193078975
PR Review Comment: https://git.openjdk.org/jdk/pull/13957#discussion_r1193079002
PR Review Comment: https://git.openjdk.org/jdk/pull/13957#discussion_r1193079017