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

[Roger Riggs]

On Wed, 17 May 2023 20:51:29 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 with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains seven additional commits since the last revision:
> 
>  - Merge
>  - 8308016: Reinstate @snippet for RandomAccessFile::readLong
>  - 8308016: Reduce linking in File::toPath snippet
>  - 8308016: Fix link in snippet of File::toPath
>  - 8308016: Address reviewer comments since previous commit
>  - 8308016: Remove ellipses ("...") from snippets
>  - 8308016: Use snippets in java.io package

src/java.base/share/classes/java/io/ByteArrayOutputStream.java line 284:

> 282:      * array such that:
> 283:      * {@snippet lang=java :
> 284:      *         c == (char)(((hibyte & 0xff) << 8) | (b & 0xff))

I'd skip the extra indentation for just the single line example.

src/java.base/share/classes/java/io/CharArrayWriter.java line 189:

> 187:      *
> 188:      * {@snippet lang=java :
> 189:      *     out.write(csq.subSequence(start, end).toString())

a trailing ";' would be useful for copy/paste; butr that's not the existing style.  Your call.

src/java.base/share/classes/java/io/Console.java line 125:

> 123:      *             Scanner sc = new Scanner(con.reader());
> 124:      *             code: // @replace substring="code:" replacement="..."
> 125:      *         }

4 space indentation would be enough.

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

> 760:      * then the result is:
> 761:      * {@snippet lang=java :
> 762:      *         (byte)(b)

4 space indent is sufficient in this file

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

PR Review Comment: https://git.openjdk.org/jdk/pull/13957#discussion_r1198146819
PR Review Comment: https://git.openjdk.org/jdk/pull/13957#discussion_r1198147802
PR Review Comment: https://git.openjdk.org/jdk/pull/13957#discussion_r1198151689
PR Review Comment: https://git.openjdk.org/jdk/pull/13957#discussion_r1198160636