RFR: 8307409: Refactor usage examples to use @snippet in the java.nio packages

[Roger Riggs]

On Mon, 8 May 2023 19:07:25 GMT, Brian Burkhalter <bpb at openjdk.org> wrote:

> Convert the `<pre>{@code ...}</pre>` and some other patterns to `{@snippet ..}`.

src/java.base/share/classes/java/nio/X-Buffer.java.template line 2244:

> 2242:      * {@snippet lang=java :
> 2243:      * nb.alignmentOffset(0, unitSize) == 0
> 2244:      * nb.alignmentOffset(nb.limit(), unitSize) == 0

The indentation (within the files) is inconsistent, I think at 4 spaces might be an improvement.

src/java.base/share/classes/java/nio/channels/SelectionKey.java line 343:

> 341:      * <blockquote><pre>{@code
> 342:      * k.readyOps() & OP_READ != 0
> 343:      * }</pre></blockquote>

The blockquote provided some indentation, that might make the example more readable.

src/java.base/share/classes/java/nio/file/Path.java line 849:

> 847:      * invocation
> 848:      * {@snippet lang=java :
> 849:      *     watchable.{@link #register(WatchService,WatchEvent.Kind[],WatchEvent.Modifier[]) register}(watcher, events, new WatchEvent.Modifier[0]);

Take out the {@link, it isn't needed and gets included literally.  (And make the line very long).

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

PR Review Comment: https://git.openjdk.org/jdk/pull/13870#discussion_r1187885244
PR Review Comment: https://git.openjdk.org/jdk/pull/13870#discussion_r1187879709
PR Review Comment: https://git.openjdk.org/jdk/pull/13870#discussion_r1187890625