From f119cf251a2c3f3ffe7e044c8862f01af16f2eba Mon Sep 17 00:00:00 2001 From: alanb Date: Fri, 28 Jun 2013 16:10:23 +0100 Subject: [PATCH] 8019380: doclint warnings in java.nio, java.nio.file.**, java.nio.channels.** Reviewed-by: chegar --- src/share/classes/java/nio/Buffer.java | 14 ++-- .../classes/java/nio/MappedByteBuffer.java | 2 +- .../classes/java/nio/X-Buffer.java.template | 64 +++++++++++-------- .../nio/channels/AsynchronousByteChannel.java | 4 ++ .../nio/channels/AsynchronousChannel.java | 2 +- .../channels/AsynchronousChannelGroup.java | 6 +- .../nio/channels/AsynchronousFileChannel.java | 8 +++ .../AsynchronousServerSocketChannel.java | 9 ++- .../channels/AsynchronousSocketChannel.java | 19 +++++- .../java/nio/channels/DatagramChannel.java | 5 +- .../java/nio/channels/FileChannel.java | 4 +- .../classes/java/nio/channels/FileLock.java | 7 +- .../java/nio/channels/MulticastChannel.java | 2 +- .../java/nio/channels/NetworkChannel.java | 4 ++ src/share/classes/java/nio/channels/Pipe.java | 13 ++-- .../java/nio/channels/SelectableChannel.java | 7 +- .../java/nio/channels/SelectionKey.java | 2 +- .../classes/java/nio/channels/Selector.java | 20 +++--- .../nio/channels/ServerSocketChannel.java | 5 +- .../java/nio/channels/SocketChannel.java | 7 +- .../spi/AbstractInterruptibleChannel.java | 2 +- .../spi/AbstractSelectableChannel.java | 10 +++ .../nio/channels/spi/AbstractSelector.java | 5 +- .../spi/AsynchronousChannelProvider.java | 4 ++ .../nio/channels/spi/SelectorProvider.java | 15 +++++ .../nio/charset/Charset-X-Coder.java.template | 16 +++++ .../classes/java/nio/charset/Charset.java | 9 ++- .../classes/java/nio/charset/CoderResult.java | 6 ++ .../java/nio/charset/spi/CharsetProvider.java | 4 +- .../classes/java/nio/file/FileStore.java | 2 + .../classes/java/nio/file/FileSystem.java | 2 +- .../classes/java/nio/file/FileSystems.java | 4 ++ src/share/classes/java/nio/file/Files.java | 23 +++++-- src/share/classes/java/nio/file/Path.java | 6 +- .../java/nio/file/SecureDirectoryStream.java | 6 ++ .../classes/java/nio/file/WatchEvent.java | 7 ++ .../classes/java/nio/file/WatchService.java | 2 +- .../java/nio/file/attribute/AclEntry.java | 18 +++++- .../file/attribute/AclFileAttributeView.java | 10 +-- .../nio/file/attribute/AttributeView.java | 2 + .../attribute/BasicFileAttributeView.java | 2 +- .../file/attribute/BasicFileAttributes.java | 11 ++++ .../file/attribute/DosFileAttributeView.java | 2 +- .../nio/file/attribute/FileAttribute.java | 4 ++ .../attribute/PosixFileAttributeView.java | 6 +- .../java/nio/file/spi/FileSystemProvider.java | 8 +++ src/share/classes/java/sql/SQLInput.java | 2 +- 47 files changed, 292 insertions(+), 100 deletions(-) diff --git a/src/share/classes/java/nio/Buffer.java b/src/share/classes/java/nio/Buffer.java index 068444a97..f5a9cd4f6 100644 --- a/src/share/classes/java/nio/Buffer.java +++ b/src/share/classes/java/nio/Buffer.java @@ -52,7 +52,7 @@ import java.util.Spliterator; *

There is one subclass of this class for each non-boolean primitive type. * * - *

Transferring data

+ *

Transferring data

* *

Each subclass of this class defines two categories of get and * put operations:

@@ -78,7 +78,7 @@ import java.util.Spliterator; * current position. * * - *

Marking and resetting

+ *

Marking and resetting

* *

A buffer's mark is the index to which its position will be reset * when the {@link #reset reset} method is invoked. The mark is not always @@ -89,7 +89,7 @@ import java.util.Spliterator; * {@link InvalidMarkException} to be thrown. * * - *

Invariants

+ *

Invariants

* *

The following invariant holds for the mark, position, limit, and * capacity values: @@ -109,7 +109,7 @@ import java.util.Spliterator; * to zero. * * - *

Clearing, flipping, and rewinding

+ *

Clearing, flipping, and rewinding

* *

In addition to methods for accessing the position, limit, and capacity * values and for marking and resetting, this class also defines the following @@ -132,7 +132,7 @@ import java.util.Spliterator; * * * - *

Read-only buffers

+ *

Read-only buffers

* *

Every buffer is readable, but not every buffer is writable. The * mutation methods of each buffer class are specified as optional @@ -143,14 +143,14 @@ import java.util.Spliterator; * {@link #isReadOnly isReadOnly} method. * * - *

Thread safety

+ *

Thread safety

* *

Buffers are not safe for use by multiple concurrent threads. If a * buffer is to be used by more than one thread then access to the buffer * should be controlled by appropriate synchronization. * * - *

Invocation chaining

+ *

Invocation chaining

* *

Methods in this class that do not otherwise have a value to return are * specified to return the buffer upon which they are invoked. This allows diff --git a/src/share/classes/java/nio/MappedByteBuffer.java b/src/share/classes/java/nio/MappedByteBuffer.java index 1d26276f1..25aa60e0b 100644 --- a/src/share/classes/java/nio/MappedByteBuffer.java +++ b/src/share/classes/java/nio/MappedByteBuffer.java @@ -45,7 +45,7 @@ import sun.misc.Unsafe; * this program or another. Whether or not such changes occur, and when they * occur, is operating-system dependent and therefore unspecified. * - *

All or part of a mapped byte buffer may become + *

All or part of a mapped byte buffer may become * inaccessible at any time, for example if the mapped file is truncated. An * attempt to access an inaccessible region of a mapped byte buffer will not * change the buffer's content and will cause an unspecified exception to be diff --git a/src/share/classes/java/nio/X-Buffer.java.template b/src/share/classes/java/nio/X-Buffer.java.template index c3037adb4..03a7255c1 100644 --- a/src/share/classes/java/nio/X-Buffer.java.template +++ b/src/share/classes/java/nio/X-Buffer.java.template @@ -44,23 +44,23 @@ import java.util.stream.$Streamtype$Stream; * *

* *

$Type$ buffers can be created either by {@link #allocate - * allocation}, which allocates space for the buffer's + * allocation}, which allocates space for the buffer's * #if[byte] * - * content, or by {@link #wrap($type$[]) wrapping} an + * content, or by {@link #wrap($type$[]) wrapping} an * existing $type$ array {#if[char]?or string} into a buffer. * #else[byte] * - * content, by {@link #wrap($type$[]) wrapping} an existing + * content, by {@link #wrap($type$[]) wrapping} an existing * $type$ array {#if[char]?or string} into a buffer, or by creating a * view of an existing byte buffer. * @@ -94,8 +94,8 @@ import java.util.stream.$Streamtype$Stream; * #if[byte] * - * - *

Direct vs. non-direct buffers

+ * + *

Direct vs. non-direct buffers

* *

A byte buffer is either direct or non-direct. Given a * direct byte buffer, the Java virtual machine will make a best effort to @@ -116,7 +116,7 @@ import java.util.stream.$Streamtype$Stream; * buffers only when they yield a measureable gain in program performance. * *

A direct byte buffer may also be created by {@link - * java.nio.channels.FileChannel#map mapping} a region of a file + * java.nio.channels.FileChannel#map mapping} a region of a file * directly into memory. An implementation of the Java platform may optionally * support the creation of direct byte buffers from native code via JNI. If an * instance of one of these kinds of buffers refers to an inaccessible region @@ -129,8 +129,8 @@ import java.util.stream.$Streamtype$Stream; * that explicit buffer management can be done in performance-critical code. * * - * - *

Access to binary data

+ * + *

Access to binary data

* *

This class defines methods for reading and writing values of all other * primitive types, except boolean. Primitive values are translated @@ -156,7 +156,7 @@ import java.util.stream.$Streamtype$Stream; * parameters of the absolute get and put methods are in terms of * bytes rather than of the type being read or written. * - * + * * *

For access to homogeneous binary data, that is, sequences of values of * the same type, this class defines methods that can create views of a @@ -214,7 +214,7 @@ import java.util.stream.$Streamtype$Stream; #end[char] * #if[byte] - *

Invocation chaining

+ *

Invocation chaining

#end[byte] * *

Methods in this class that do not otherwise have a value to return are @@ -297,7 +297,7 @@ public abstract class $Type$Buffer *

The new buffer's position will be zero, its limit will be its * capacity, its mark will be undefined, and each of its elements will be * initialized to zero. Whether or not it has a - * {@link #hasArray backing array} is unspecified. + * {@link #hasArray backing array} is unspecified. * * @param capacity * The new buffer's capacity, in $type$s @@ -318,9 +318,8 @@ public abstract class $Type$Buffer * *

The new buffer's position will be zero, its limit will be its * capacity, its mark will be undefined, and each of its elements will be - * initialized to zero. It will have a {@link #array - * backing array}, and its {@link #arrayOffset array - * offset} will be zero. + * initialized to zero. It will have a {@link #array backing array}, + * and its {@link #arrayOffset array offset} will be zero. * * @param capacity * The new buffer's capacity, in $type$s @@ -344,8 +343,8 @@ public abstract class $Type$Buffer * and vice versa. The new buffer's capacity will be * array.length, its position will be offset, its limit * will be offset + length, and its mark will be undefined. Its - * {@link #array backing array} will be the given array, and - * its {@link #arrayOffset array offset} will be zero.

+ * {@link #array backing array} will be the given array, and + * its {@link #arrayOffset array offset} will be zero.

* * @param array * The array that will back the new buffer @@ -384,8 +383,8 @@ public abstract class $Type$Buffer * that is, modifications to the buffer will cause the array to be modified * and vice versa. The new buffer's capacity and limit will be * array.length, its position will be zero, and its mark will be - * undefined. Its {@link #array backing array} will be the - * given array, and its {@link #arrayOffset array offset} will + * undefined. Its {@link #array backing array} will be the + * given array, and its {@link #arrayOffset array offset>} will * be zero.

* * @param array @@ -703,6 +702,9 @@ public abstract class $Type$Buffer * 
      *     src.get(a, 0, a.length)
* + * @param dst + * The destination array + * * @return This buffer * * @throws BufferUnderflowException @@ -842,6 +844,9 @@ public abstract class $Type$Buffer * 
      *     dst.put(a, 0, a.length)
* + * @param src + * The source array + * * @return This buffer * * @throws BufferOverflowException @@ -930,6 +935,9 @@ public abstract class $Type$Buffer * 
      *     dst.put(s, 0, s.length())
* + * @param src + * The source string + * * @return This buffer * * @throws BufferOverflowException @@ -1419,7 +1427,7 @@ public abstract class $Type$Buffer * *

The byte order of $a$ $type$ buffer created by allocation or by * wrapping an existing $type$ array is the {@link - * ByteOrder#nativeOrder native order} of the underlying + * ByteOrder#nativeOrder native order} of the underlying * hardware. The byte order of $a$ $type$ buffer created as a view of a byte buffer is that of the * byte buffer at the moment that the view is created.

diff --git a/src/share/classes/java/nio/channels/AsynchronousByteChannel.java b/src/share/classes/java/nio/channels/AsynchronousByteChannel.java index 9fdf7530d..47ffc87a8 100644 --- a/src/share/classes/java/nio/channels/AsynchronousByteChannel.java +++ b/src/share/classes/java/nio/channels/AsynchronousByteChannel.java @@ -87,6 +87,8 @@ public interface AsynchronousByteChannel * initiates a read operation before a previous read operation has * completed then a {@link ReadPendingException} will be thrown. * + * @param + * The type of the attachment * @param dst * The buffer into which bytes are to be transferred * @param attachment @@ -166,6 +168,8 @@ public interface AsynchronousByteChannel * initiates a write operation before a previous write operation has * completed then a {@link WritePendingException} will be thrown. * + * @param + * The type of the attachment * @param src * The buffer from which bytes are to be retrieved * @param attachment diff --git a/src/share/classes/java/nio/channels/AsynchronousChannel.java b/src/share/classes/java/nio/channels/AsynchronousChannel.java index 5aa9fe23b..98e30d05e 100644 --- a/src/share/classes/java/nio/channels/AsynchronousChannel.java +++ b/src/share/classes/java/nio/channels/AsynchronousChannel.java @@ -61,7 +61,7 @@ import java.util.concurrent.Future; // javadoc * may not allow more than one read and one write operation to be outstanding at * any given time. * - *

Cancellation

+ *

Cancellation

* *

The {@code Future} interface defines the {@link Future#cancel cancel} * method to cancel execution. This causes all threads waiting on the result of diff --git a/src/share/classes/java/nio/channels/AsynchronousChannelGroup.java b/src/share/classes/java/nio/channels/AsynchronousChannelGroup.java index 2eb4b5219..ace607323 100644 --- a/src/share/classes/java/nio/channels/AsynchronousChannelGroup.java +++ b/src/share/classes/java/nio/channels/AsynchronousChannelGroup.java @@ -60,7 +60,7 @@ import java.util.concurrent.TimeUnit; * default group is not configured then the pooled threads of the default group * are {@link Thread#isDaemon daemon} threads. * - * + *
* * * @@ -89,7 +89,7 @@ import java.util.concurrent.TimeUnit; * *
System propertyDescription
* - *

Threading

+ *

Threading

* *

The completion handler for an I/O operation initiated on a channel bound * to a group is guaranteed to be invoked by one of the pooled threads in the @@ -104,7 +104,7 @@ import java.util.concurrent.TimeUnit; * handler directly by the initiating thread (see {@link * AsynchronousServerSocketChannel#accept(Object,CompletionHandler) accept}). * - *

Shutdown and Termination

+ *

Shutdown and Termination

* *

The {@link #shutdown() shutdown} method is used to initiate an orderly * shutdown of a group. An orderly shutdown marks the group as shutdown; diff --git a/src/share/classes/java/nio/channels/AsynchronousFileChannel.java b/src/share/classes/java/nio/channels/AsynchronousFileChannel.java index b1c6e788c..c40fb3762 100644 --- a/src/share/classes/java/nio/channels/AsynchronousFileChannel.java +++ b/src/share/classes/java/nio/channels/AsynchronousFileChannel.java @@ -425,6 +425,8 @@ public abstract class AsynchronousFileChannel * They are not suitable for controlling access to a file by multiple * threads within the same virtual machine. * + * @param + * The type of the attachment * @param position * The position at which the locked region is to start; must be * non-negative @@ -473,6 +475,8 @@ public abstract class AsynchronousFileChannel * ch.{@link #lock(long,long,boolean,Object,CompletionHandler) lock}(0L, Long.MAX_VALUE, false, att, handler) * * + * @param + * The type of the attachment * @param attachment * The object to attach to the I/O operation; can be {@code null} * @param handler @@ -652,6 +656,8 @@ public abstract class AsynchronousFileChannel * If the given file position is greater than the file's size at the time * that the read is attempted then no bytes are read. * + * @param + * The type of the attachment * @param dst * The buffer into which bytes are to be transferred * @param position @@ -716,6 +722,8 @@ public abstract class AsynchronousFileChannel * bytes; the values of any bytes between the previous end-of-file and the * newly-written bytes are unspecified. * + * @param + * The type of the attachment * @param src * The buffer from which bytes are to be transferred * @param position diff --git a/src/share/classes/java/nio/channels/AsynchronousServerSocketChannel.java b/src/share/classes/java/nio/channels/AsynchronousServerSocketChannel.java index 477855572..75882008b 100644 --- a/src/share/classes/java/nio/channels/AsynchronousServerSocketChannel.java +++ b/src/share/classes/java/nio/channels/AsynchronousServerSocketChannel.java @@ -52,7 +52,7 @@ import java.io.IOException; *

Socket options are configured using the {@link #setOption(SocketOption,Object) * setOption} method. Channels of this type support the following options: *

- * + *
* * * @@ -98,6 +98,9 @@ public abstract class AsynchronousServerSocketChannel /** * Initializes a new instance of this class. + * + * @param provider + * The provider that created this channel */ protected AsynchronousServerSocketChannel(AsynchronousChannelProvider provider) { this.provider = provider; @@ -105,6 +108,8 @@ public abstract class AsynchronousServerSocketChannel /** * Returns the provider that created this channel. + * + * @return The provider that created this channel */ public final AsynchronousChannelProvider provider() { return provider; @@ -263,6 +268,8 @@ public abstract class AsynchronousServerSocketChannel * the connection is closed and the operation completes with a {@link * SecurityException}. * + * @param + * The type of the attachment * @param attachment * The object to attach to the I/O operation; can be {@code null} * @param handler diff --git a/src/share/classes/java/nio/channels/AsynchronousSocketChannel.java b/src/share/classes/java/nio/channels/AsynchronousSocketChannel.java index 74c93c872..2c2a1a306 100644 --- a/src/share/classes/java/nio/channels/AsynchronousSocketChannel.java +++ b/src/share/classes/java/nio/channels/AsynchronousSocketChannel.java @@ -62,7 +62,7 @@ import java.nio.ByteBuffer; *

Socket options are configured using the {@link #setOption(SocketOption,Object) * setOption} method. Asynchronous socket channels support the following options: *

- *
Option NameDescription
 + *
* * * @@ -91,7 +91,7 @@ import java.nio.ByteBuffer; * * Additional (implementation specific) options may also be supported. * - *

Timeouts

+ *

Timeouts

* *

The {@link #read(ByteBuffer,long,TimeUnit,Object,CompletionHandler) read} * and {@link #write(ByteBuffer,long,TimeUnit,Object,CompletionHandler) write} @@ -123,6 +123,9 @@ public abstract class AsynchronousSocketChannel /** * Initializes a new instance of this class. + * + * @param provider + * The provider that created this channel */ protected AsynchronousSocketChannel(AsynchronousChannelProvider provider) { this.provider = provider; @@ -130,6 +133,8 @@ public abstract class AsynchronousSocketChannel /** * Returns the provider that created this channel. + * + * @return The provider that created this channel */ public final AsynchronousChannelProvider provider() { return provider; @@ -287,6 +292,8 @@ public abstract class AsynchronousSocketChannel * java.lang.SecurityManager#checkConnect checkConnect} method permits * connecting to the address and port number of the given remote endpoint. * + * @param + * The type of the attachment * @param remote * The remote address to which this channel is to be connected * @param attachment @@ -365,6 +372,8 @@ public abstract class AsynchronousSocketChannel * AsynchronousByteChannel#read(ByteBuffer,Object,CompletionHandler)} * method. * + * @param + * The type of the attachment * @param dst * The buffer into which bytes are to be transferred * @param timeout @@ -461,6 +470,8 @@ public abstract class AsynchronousSocketChannel * read from the channel will cause an unspecific runtime exception to be * thrown. * + * @param + * The type of the attachment * @param dsts * The buffers into which bytes are to be transferred * @param offset @@ -520,6 +531,8 @@ public abstract class AsynchronousSocketChannel * AsynchronousByteChannel#write(ByteBuffer,Object,CompletionHandler)} * method. * + * @param + * The type of the attachment * @param src * The buffer from which bytes are to be retrieved * @param timeout @@ -610,6 +623,8 @@ public abstract class AsynchronousSocketChannel * to write to the channel will cause an unspecific runtime exception to be * thrown. * + * @param + * The type of the attachment * @param srcs * The buffers from which bytes are to be retrieved * @param offset diff --git a/src/share/classes/java/nio/channels/DatagramChannel.java b/src/share/classes/java/nio/channels/DatagramChannel.java index fd8b920ee..3626317a9 100644 --- a/src/share/classes/java/nio/channels/DatagramChannel.java +++ b/src/share/classes/java/nio/channels/DatagramChannel.java @@ -57,7 +57,7 @@ import java.nio.channels.spi.SelectorProvider; * setOption} method. A datagram channel to an Internet Protocol socket supports * the following options: *

- *
Option NameDescription
+ *
* * * @@ -117,6 +117,9 @@ public abstract class DatagramChannel /** * Initializes a new instance of this class. + * + * @param provider + * The provider that created this channel */ protected DatagramChannel(SelectorProvider provider) { super(provider); diff --git a/src/share/classes/java/nio/channels/FileChannel.java b/src/share/classes/java/nio/channels/FileChannel.java index 02d9082d2..57ce3e10d 100644 --- a/src/share/classes/java/nio/channels/FileChannel.java +++ b/src/share/classes/java/nio/channels/FileChannel.java @@ -46,7 +46,7 @@ import java.util.Collections; * of bytes that can be read and written and whose current {@link #size * size} can be queried. The size of the file increases * when bytes are written beyond its current size; the size of the file - * decreases when it is {@link #truncate truncated}. The + * decreases when it is {@link #truncate truncated}. The * file may also have some associated metadata such as access * permissions, content type, and last-modification time; this class does not * define methods for metadata access. @@ -830,7 +830,7 @@ public abstract class FileChannel *

A region of a file may be mapped into memory in one of three modes: *

* - *
    + *
      * *

    • Read-only: Any attempt to modify the resulting buffer * will cause a {@link java.nio.ReadOnlyBufferException} to be thrown. diff --git a/src/share/classes/java/nio/channels/FileLock.java b/src/share/classes/java/nio/channels/FileLock.java index e978af431..fb584ee16 100644 --- a/src/share/classes/java/nio/channels/FileLock.java +++ b/src/share/classes/java/nio/channels/FileLock.java @@ -72,7 +72,7 @@ import java.io.IOException; *

      File-lock objects are safe for use by multiple concurrent threads. * * - *

      Platform dependencies

      + *

      Platform dependencies

      * *

      This file-locking API is intended to map directly to the native locking * facility of the underlying operating system. Thus the locks held on a file @@ -261,6 +261,11 @@ public abstract class FileLock implements AutoCloseable { /** * Tells whether or not this lock overlaps the given lock range. * + * @param position + * The starting position of the lock range + * @param size + * The size of the lock range + * * @return true if, and only if, this lock and the given lock * range overlap by at least one byte */ diff --git a/src/share/classes/java/nio/channels/MulticastChannel.java b/src/share/classes/java/nio/channels/MulticastChannel.java index 0e06633b5..ca17e2415 100644 --- a/src/share/classes/java/nio/channels/MulticastChannel.java +++ b/src/share/classes/java/nio/channels/MulticastChannel.java @@ -71,7 +71,7 @@ import java.net.StandardSocketOptions; // javadoc * MembershipKey#drop drop} method drops membership so that datagrams from the * source address can no longer be received. * - *

      Platform dependencies

      + *

      Platform dependencies

      * * The multicast implementation is intended to map directly to the native * multicasting facility. Consequently, the following items should be considered diff --git a/src/share/classes/java/nio/channels/NetworkChannel.java b/src/share/classes/java/nio/channels/NetworkChannel.java index 3900f9d28..b56b5e25c 100644 --- a/src/share/classes/java/nio/channels/NetworkChannel.java +++ b/src/share/classes/java/nio/channels/NetworkChannel.java @@ -106,6 +106,8 @@ public interface NetworkChannel /** * Sets the value of a socket option. * + * @param + * The type of the socket option value * @param name * The socket option * @param value @@ -130,6 +132,8 @@ public interface NetworkChannel /** * Returns the value of a socket option. * + * @param + * The type of the socket option value * @param name * The socket option * diff --git a/src/share/classes/java/nio/channels/Pipe.java b/src/share/classes/java/nio/channels/Pipe.java index af0722e99..4b5a5a51c 100644 --- a/src/share/classes/java/nio/channels/Pipe.java +++ b/src/share/classes/java/nio/channels/Pipe.java @@ -33,10 +33,9 @@ import java.nio.channels.spi.*; * A pair of channels that implements a unidirectional pipe. * *

      A pipe consists of a pair of channels: A writable {@link - * Pipe.SinkChannel sink} channel and a readable {@link - * Pipe.SourceChannel source} channel. Once some bytes are - * written to the sink channel they can be read from source channel in exactly - * the order in which they were written. + * Pipe.SinkChannel sink} channel and a readable {@link Pipe.SourceChannel source} + * channel. Once some bytes are written to the sink channel they can be read + * from source channel in exactlyAthe order in which they were written. * *

      Whether or not a thread writing bytes to a pipe will block until another * thread reads those bytes, or some previously-written bytes, from the pipe is @@ -63,6 +62,9 @@ public abstract class Pipe { { /** * Constructs a new instance of this class. + * + * @param provider + * The selector provider */ protected SourceChannel(SelectorProvider provider) { super(provider); @@ -94,6 +96,9 @@ public abstract class Pipe { { /** * Initializes a new instance of this class. + * + * @param provider + * The selector provider */ protected SinkChannel(SelectorProvider provider) { super(provider); diff --git a/src/share/classes/java/nio/channels/SelectableChannel.java b/src/share/classes/java/nio/channels/SelectableChannel.java index 7041c34e1..17f86831d 100644 --- a/src/share/classes/java/nio/channels/SelectableChannel.java +++ b/src/share/classes/java/nio/channels/SelectableChannel.java @@ -64,8 +64,8 @@ import java.nio.channels.spi.SelectorProvider; * threads.

      * * - * - *

      Blocking mode

      + *       + *

      Blocking mode

      * * A selectable channel is either in blocking mode or in * non-blocking mode. In blocking mode, every I/O operation invoked @@ -142,6 +142,9 @@ public abstract class SelectableChannel * Retrieves the key representing the channel's registration with the given * selector. * + * @param sel + * The selector + * * @return The key returned when this channel was last registered with the * given selector, or null if this channel is not * currently registered with that selector diff --git a/src/share/classes/java/nio/channels/SelectionKey.java b/src/share/classes/java/nio/channels/SelectionKey.java index 7a0ab88ac..e140ee619 100644 --- a/src/share/classes/java/nio/channels/SelectionKey.java +++ b/src/share/classes/java/nio/channels/SelectionKey.java @@ -42,7 +42,7 @@ import java.io.IOException; * next selection operation. The validity of a key may be tested by invoking * its {@link #isValid isValid} method. * - * + * * *

      A selection key contains two operation sets represented as * integer values. Each bit of an operation set denotes a category of diff --git a/src/share/classes/java/nio/channels/Selector.java b/src/share/classes/java/nio/channels/Selector.java index d4c200e69..3f21727f2 100644 --- a/src/share/classes/java/nio/channels/Selector.java +++ b/src/share/classes/java/nio/channels/Selector.java @@ -36,13 +36,13 @@ import java.util.Set; * *

      A selector may be created by invoking the {@link #open open} method of * this class, which will use the system's default {@link - * java.nio.channels.spi.SelectorProvider selector provider} to + * java.nio.channels.spi.SelectorProvider selector provider} to * create a new selector. A selector may also be created by invoking the * {@link java.nio.channels.spi.SelectorProvider#openSelector openSelector} * method of a custom selector provider. A selector remains open until it is * closed via its {@link #close close} method. * - * + * * *

      A selectable channel's registration with a selector is represented by a * {@link SelectionKey} object. A selector maintains three sets of selection @@ -80,18 +80,18 @@ import java.util.Set; * during the next selection operation, at which time the key will removed from * all of the selector's key sets. * - *

      Keys are added to the selected-key set by selection + *

      Keys are added to the selected-key set by selection * operations. A key may be removed directly from the selected-key set by * invoking the set's {@link java.util.Set#remove(java.lang.Object) remove} * method or by invoking the {@link java.util.Iterator#remove() remove} method - * of an {@link java.util.Iterator iterator} obtained from the + * of an {@link java.util.Iterator iterator} obtained from the * set. Keys are never removed from the selected-key set in any other way; * they are not, in particular, removed as a side effect of selection * operations. Keys may not be added directly to the selected-key set.

      * * - * - *

      Selection

      + *       + *

      Selection

      * *

      During each selection operation, keys may be added to and removed from a * selector's selected-key set and may be removed from its key and @@ -111,7 +111,7 @@ import java.util.Set; * operation began. For a channel that is ready for at least one such * operation, one of the following two actions is performed:

      * - *
        + *
          * *

        1. If the channel's key is not already in the selected-key set then * it is added to that set and its ready-operation set is modified to @@ -126,7 +126,7 @@ import java.util.Set; * words, the ready set returned by the underlying system is * bitwise-disjoined into the key's current ready set.

          2. * - *
        + *
      * * If all of the keys in the key set at the start of this step have empty * interest sets then neither the selected-key set nor any of the keys' @@ -142,7 +142,7 @@ import java.util.Set; * difference between the three selection methods.

      * * - *

      Concurrency

      + *

      Concurrency

      * *

      Selectors are themselves safe for use by multiple concurrent threads; * their key sets, however, are not. @@ -183,7 +183,7 @@ import java.util.Set; *

      The {@link #close close} method synchronizes on the selector and all * three key sets in the same order as in a selection operation. * - * + * * *

      A selector's key and selected-key sets are not, in general, safe for use * by multiple concurrent threads. If such a thread might modify one of these diff --git a/src/share/classes/java/nio/channels/ServerSocketChannel.java b/src/share/classes/java/nio/channels/ServerSocketChannel.java index 90e39b529..aeda90df0 100644 --- a/src/share/classes/java/nio/channels/ServerSocketChannel.java +++ b/src/share/classes/java/nio/channels/ServerSocketChannel.java @@ -46,7 +46,7 @@ import java.nio.channels.spi.SelectorProvider; *

      Socket options are configured using the {@link #setOption(SocketOption,Object) * setOption} method. Server-socket channels support the following options: *

      - *
Option NameDescription
+ *
* * * @@ -78,6 +78,9 @@ public abstract class ServerSocketChannel /** * Initializes a new instance of this class. + * + * @param provider + * The provider that created this channel */ protected ServerSocketChannel(SelectorProvider provider) { super(provider); diff --git a/src/share/classes/java/nio/channels/SocketChannel.java b/src/share/classes/java/nio/channels/SocketChannel.java index 620332649..091570cbf 100644 --- a/src/share/classes/java/nio/channels/SocketChannel.java +++ b/src/share/classes/java/nio/channels/SocketChannel.java @@ -66,7 +66,7 @@ import java.nio.channels.spi.SelectorProvider; *

Socket options are configured using the {@link #setOption(SocketOption,Object) * setOption} method. Socket channels support the following options: *

- *
Option NameDescription
+ *
* * * @@ -120,6 +120,9 @@ public abstract class SocketChannel /** * Initializes a new instance of this class. + * + * @param provider + * The provider that created this channel */ protected SocketChannel(SelectorProvider provider) { super(provider); @@ -153,6 +156,8 @@ public abstract class SocketChannel * @param remote * The remote address to which the new channel is to be connected * + * @return A new, and connected, socket channel + * * @throws AsynchronousCloseException * If another thread closes this channel * while the connect operation is in progress diff --git a/src/share/classes/java/nio/channels/spi/AbstractInterruptibleChannel.java b/src/share/classes/java/nio/channels/spi/AbstractInterruptibleChannel.java index a5936832b..c8400692e 100644 --- a/src/share/classes/java/nio/channels/spi/AbstractInterruptibleChannel.java +++ b/src/share/classes/java/nio/channels/spi/AbstractInterruptibleChannel.java @@ -46,7 +46,7 @@ import sun.nio.ch.Interruptible; * before and after, respectively, invoking an I/O operation that might block * indefinitely. In order to ensure that the {@link #end end} method is always * invoked, these methods should be used within a - * try ... finally block: + * try ... finally block: * * 
  * boolean completed = false;
diff --git a/src/share/classes/java/nio/channels/spi/AbstractSelectableChannel.java b/src/share/classes/java/nio/channels/spi/AbstractSelectableChannel.java
index e674d5017..5d1b1ee99 100644
--- a/src/share/classes/java/nio/channels/spi/AbstractSelectableChannel.java
+++ b/src/share/classes/java/nio/channels/spi/AbstractSelectableChannel.java
@@ -72,6 +72,9 @@ public abstract class AbstractSelectableChannel
 
     /**
      * Initializes a new instance of this class.
+     *
+     * @param  provider
+     *         The provider that created this channel
      */
     protected AbstractSelectableChannel(SelectorProvider provider) {
         this.provider = provider;
@@ -251,6 +254,9 @@ public abstract class AbstractSelectableChannel
      * that is blocked in an I/O operation upon this channel to return
      * immediately, either by throwing an exception or by returning normally.
      * 

+     *
+     * @throws  IOException
+     *          If an I/O error occurs
      */
     protected abstract void implCloseSelectableChannel() throws IOException;
 
@@ -299,6 +305,10 @@ public abstract class AbstractSelectableChannel
      * changing the blocking mode.  This method is only invoked if the new mode
      * is different from the current mode.  

      *
+     * @param  block  If true then this channel will be placed in
+     *                blocking mode; if false then it will be placed
+     *                non-blocking mode
+     *
      * @throws IOException
      *         If an I/O error occurs
      */
diff --git a/src/share/classes/java/nio/channels/spi/AbstractSelector.java b/src/share/classes/java/nio/channels/spi/AbstractSelector.java
index fea4b0972..f4f4a2a74 100644
--- a/src/share/classes/java/nio/channels/spi/AbstractSelector.java
+++ b/src/share/classes/java/nio/channels/spi/AbstractSelector.java
@@ -43,7 +43,7 @@ import java.util.concurrent.atomic.AtomicBoolean;
  * after, respectively, invoking an I/O operation that might block
  * indefinitely.  In order to ensure that the {@link #end end} method is always
  * invoked, these methods should be used within a
- * try ... finally block: 
+ * try ... finally block:
  *
  * 
  * try {
@@ -77,6 +77,9 @@ public abstract class AbstractSelector
 
     /**
      * Initializes a new instance of this class.
+     *
+     * @param  provider
+     *         The provider that created this selector
      */
     protected AbstractSelector(SelectorProvider provider) {
         this.provider = provider;
diff --git a/src/share/classes/java/nio/channels/spi/AsynchronousChannelProvider.java b/src/share/classes/java/nio/channels/spi/AsynchronousChannelProvider.java
index 827a2c5b9..e768e475c 100644
--- a/src/share/classes/java/nio/channels/spi/AsynchronousChannelProvider.java
+++ b/src/share/classes/java/nio/channels/spi/AsynchronousChannelProvider.java
@@ -174,6 +174,8 @@ public abstract class AsynchronousChannelProvider {
      * @param   threadFactory
      *          The factory to use when creating new threads
      *
+     * @return  A new asynchronous channel group
+     *
      * @throws  IllegalArgumentException
      *          If {@code nThreads <= 0}
      * @throws  IOException
@@ -193,6 +195,8 @@ public abstract class AsynchronousChannelProvider {
      *          A value {@code >=0} or a negative value for implementation
      *          specific default
      *
+     * @return  A new asynchronous channel group
+     *
      * @throws  IOException
      *          If an I/O error occurs
      *
diff --git a/src/share/classes/java/nio/channels/spi/SelectorProvider.java b/src/share/classes/java/nio/channels/spi/SelectorProvider.java
index 62d4bf6ff..8d74b43cf 100644
--- a/src/share/classes/java/nio/channels/spi/SelectorProvider.java
+++ b/src/share/classes/java/nio/channels/spi/SelectorProvider.java
@@ -183,6 +183,9 @@ public abstract class SelectorProvider {
      * Opens a datagram channel.
      *
      * @return  The new channel
+     *
+     * @throws  IOException
+     *          If an I/O error occurs
      */
     public abstract DatagramChannel openDatagramChannel()
         throws IOException;
@@ -209,6 +212,9 @@ public abstract class SelectorProvider {
      * Opens a pipe.
      *
      * @return  The new pipe
+     *
+     * @throws  IOException
+     *          If an I/O error occurs
      */
     public abstract Pipe openPipe()
         throws IOException;
@@ -217,6 +223,9 @@ public abstract class SelectorProvider {
      * Opens a selector.
      *
      * @return  The new selector
+     *
+     * @throws  IOException
+     *          If an I/O error occurs
      */
     public abstract AbstractSelector openSelector()
         throws IOException;
@@ -225,6 +234,9 @@ public abstract class SelectorProvider {
      * Opens a server-socket channel.
      *
      * @return  The new channel
+     *
+     * @throws  IOException
+     *          If an I/O error occurs
      */
     public abstract ServerSocketChannel openServerSocketChannel()
         throws IOException;
@@ -233,6 +245,9 @@ public abstract class SelectorProvider {
      * Opens a socket channel.
      *
      * @return  The new channel
+     *
+     * @throws  IOException
+     *          If an I/O error occurs
      */
     public abstract SocketChannel openSocketChannel()
         throws IOException;
diff --git a/src/share/classes/java/nio/charset/Charset-X-Coder.java.template b/src/share/classes/java/nio/charset/Charset-X-Coder.java.template
index 34be4eb83..335194eef 100644
--- a/src/share/classes/java/nio/charset/Charset-X-Coder.java.template
+++ b/src/share/classes/java/nio/charset/Charset-X-Coder.java.template
@@ -163,6 +163,9 @@ public abstract class Charset$Coder$ {
      * Initializes a new $coder$.  The new $coder$ will have the given
      * $otypes-per-itype$ and replacement values.
      *
+     * @param  cs
+     *         The charset that created this $coder$
+     *
      * @param  average$ItypesPerOtype$
      *         A positive float value indicating the expected number of
      *         $otype$s that will be produced for each input $itype$
@@ -209,6 +212,9 @@ public abstract class Charset$Coder$ {
      * $otypes-per-itype$ values and its replacement will be the
      * $replTypeName$ $defaultReplName$.
      *
+     * @param  cs
+     *         The charset that created this $coder$
+     *
      * @param  average$ItypesPerOtype$
      *         A positive float value indicating the expected number of
      *         $otype$s that will be produced for each input $itype$
@@ -386,6 +392,8 @@ public abstract class Charset$Coder$ {
      * 
 The default implementation of this method does nothing.  This method
      * should be overridden by $coder$s that require notification of changes to
      * the malformed-input action.  

+     *
+     * @param  newAction  The new action
      */
     protected void implOnMalformedInput(CodingErrorAction newAction) { }
 
@@ -428,6 +436,8 @@ public abstract class Charset$Coder$ {
      * 
 The default implementation of this method does nothing.  This method
      * should be overridden by $coder$s that require notification of changes to
      * the unmappable-character action.  

+     *
+     * @param  newAction  The new action
      */
     protected void implOnUnmappableCharacter(CodingErrorAction newAction) { }
 
@@ -925,6 +935,9 @@ public abstract class Charset$Coder$ {
      * 
 The default implementation of this method is not very efficient; it
      * should generally be overridden to improve performance.  

      *
+     * @param   c
+     *          The given character
+     *
      * @return  true if, and only if, this encoder can encode
      *          the given character
      *
@@ -953,6 +966,9 @@ public abstract class Charset$Coder$ {
      * 
 The default implementation of this method is not very efficient; it
      * should generally be overridden to improve performance.  

      *
+     * @param   cs
+     *          The given character sequence
+     *
      * @return  true if, and only if, this encoder can encode
      *          the given character without throwing any exceptions and without
      *          performing any replacements
diff --git a/src/share/classes/java/nio/charset/Charset.java b/src/share/classes/java/nio/charset/Charset.java
index 69c3ab0e1..278bacb17 100644
--- a/src/share/classes/java/nio/charset/Charset.java
+++ b/src/share/classes/java/nio/charset/Charset.java
@@ -66,7 +66,7 @@ import sun.security.action.GetPropertyAction;
  *
  *
  * 
- * 
Charset names

+ * 
Charset names

  *
  * 
 Charsets are named by strings composed of the following characters:
  *
@@ -140,7 +140,7 @@ import sun.security.action.GetPropertyAction;
  * previous canonical name be made into an alias.
  *
  *
- * 
Standard charsets

+ * 
Standard charsets

  *
  * 
  *
@@ -217,7 +217,7 @@ import sun.security.action.GetPropertyAction;
  * 
The {@link StandardCharsets} class defines constants for each of the
  * standard charsets.
  *
- * 
Terminology

+ * 
Terminology

  *
  * 
 The name of this class is taken from the terms used in
  * RFC 2278.
@@ -737,6 +737,9 @@ public abstract class Charset
      * it is not necessarily the case that the given charset is not contained
      * in this charset.
      *
+     * @param   cs
+     *          The given charset
+     *
      * @return  true if the given charset is contained in this charset
      */
     public abstract boolean contains(Charset cs);
diff --git a/src/share/classes/java/nio/charset/CoderResult.java b/src/share/classes/java/nio/charset/CoderResult.java
index 5b2c4d41f..15aad362c 100644
--- a/src/share/classes/java/nio/charset/CoderResult.java
+++ b/src/share/classes/java/nio/charset/CoderResult.java
@@ -227,6 +227,9 @@ public class CoderResult {
      * Static factory method that returns the unique object describing a
      * malformed-input error of the given length.
      *
+     * @param   length
+     *          The given length
+     *
      * @return  The requested coder-result object
      */
     public static CoderResult malformedForLength(int length) {
@@ -243,6 +246,9 @@ public class CoderResult {
      * Static factory method that returns the unique result object describing
      * an unmappable-character error of the given length.
      *
+     * @param   length
+     *          The given length
+     *
      * @return  The requested coder-result object
      */
     public static CoderResult unmappableForLength(int length) {
diff --git a/src/share/classes/java/nio/charset/spi/CharsetProvider.java b/src/share/classes/java/nio/charset/spi/CharsetProvider.java
index 3525e201d..1e31d75fe 100644
--- a/src/share/classes/java/nio/charset/spi/CharsetProvider.java
+++ b/src/share/classes/java/nio/charset/spi/CharsetProvider.java
@@ -39,8 +39,8 @@ import java.util.Iterator;
  * the usual extension directories.  Providers may also be made available by
  * adding them to the applet or application class path or by some other
  * platform-specific means.  Charset providers are looked up via the current
- * thread's {@link java.lang.Thread#getContextClassLoader() context
- * class loader}.
+ * thread's {@link java.lang.Thread#getContextClassLoader() context class
+ * loader}.
  *
  * 
 A charset provider identifies itself with a provider-configuration file
  * named java.nio.charset.spi.CharsetProvider in the resource
diff --git a/src/share/classes/java/nio/file/FileStore.java b/src/share/classes/java/nio/file/FileStore.java
index 831dba8a5..d0bdc0139 100644
--- a/src/share/classes/java/nio/file/FileStore.java
+++ b/src/share/classes/java/nio/file/FileStore.java
@@ -173,6 +173,8 @@ public abstract class FileStore {
      * The {@code type} parameter is the type of the attribute view required and
      * the method returns an instance of that type if supported.
      *
+     * @param   
+     *          The {@code FileStoreAttributeView} type
      * @param   type
      *          the {@code Class} object corresponding to the attribute view
      *
diff --git a/src/share/classes/java/nio/file/FileSystem.java b/src/share/classes/java/nio/file/FileSystem.java
index e21660798..2296cada8 100644
--- a/src/share/classes/java/nio/file/FileSystem.java
+++ b/src/share/classes/java/nio/file/FileSystem.java
@@ -315,7 +315,7 @@ public abstract class FileSystem
      * that resembles regular expressions but with a simpler syntax. For example:
      *
      * 

-     *
Option NameDescription
+ *
* * * diff --git a/src/share/classes/java/nio/file/FileSystems.java b/src/share/classes/java/nio/file/FileSystems.java index ef443640a..d6b4496dd 100644 --- a/src/share/classes/java/nio/file/FileSystems.java +++ b/src/share/classes/java/nio/file/FileSystems.java @@ -200,6 +200,10 @@ public final class FileSystems { * existing file system. In the case of the {@link FileSystems#getDefault * default} file system, no permission check is required. * + * @param uri the URI to locate the file system + * + * @return the reference to the file system + * * @throws IllegalArgumentException * if the pre-conditions for the {@code uri} parameter are not met * @throws FileSystemNotFoundException diff --git a/src/share/classes/java/nio/file/Files.java b/src/share/classes/java/nio/file/Files.java index c4065690a..ca0263d06 100644 --- a/src/share/classes/java/nio/file/Files.java +++ b/src/share/classes/java/nio/file/Files.java @@ -194,7 +194,7 @@ public final class Files { *

In the addition to {@code READ} and {@code WRITE}, the following * options may be present: * - *

{@code *.java}Matches a path that represents a file name ending in {@code .java}
+ *
* * * @@ -1616,7 +1616,8 @@ public final class Files { * } * * - * + * @param + * The {@code FileAttributeView} type * @param path * the path to the file * @param type @@ -1665,6 +1666,8 @@ public final class Files { * PosixFileAttributes attrs = Files.readAttributes(path, PosixFileAttributes.class, NOFOLLOW_LINKS); * * + * @param + * The {@code BasicFileAttributes} type * @param path * the path to the file * @param type @@ -1863,7 +1866,7 @@ public final class Files { * attributes} parameter: * *
- *
Option Description
{@link StandardOpenOption#APPEND APPEND}
+ *
* * * @@ -1971,10 +1974,12 @@ public final class Files { * System Interface (POSIX) family of standards. * * @param path - * A file reference that locates the file + * The path to the file * @param perms * The new set of permissions * + * @return The path + * * @throws UnsupportedOperationException * if the associated file system does not support the {@code * PosixFileAttributeView} @@ -2009,7 +2014,7 @@ public final class Files { * access to a file attribute that is the owner of the file. * * @param path - * A file reference that locates the file + * The path to the file * @param options * options indicating how symbolic links are handled * @@ -2052,10 +2057,12 @@ public final class Files { * * * @param path - * A file reference that locates the file + * The path to the file * @param owner * The new file owner * + * @return The path + * * @throws UnsupportedOperationException * if the associated file system does not support the {@code * FileOwnerAttributeView} @@ -2090,6 +2097,8 @@ public final class Files { * readAttributes} method and the file type tested with the {@link * BasicFileAttributes#isSymbolicLink} method. * + * @param path The path to the file + * * @return {@code true} if the file is a symbolic link; {@code false} if * the file does not exist, is not a symbolic link, or it cannot * be determined if the file is a symbolic link or not. @@ -2239,7 +2248,7 @@ public final class Files { * @param time * the new last modified time * - * @return the file + * @return the path * * @throws IOException * if an I/O error occurs diff --git a/src/share/classes/java/nio/file/Path.java b/src/share/classes/java/nio/file/Path.java index 577827658..39afd4d42 100644 --- a/src/share/classes/java/nio/file/Path.java +++ b/src/share/classes/java/nio/file/Path.java @@ -64,7 +64,7 @@ import java.util.Iterator; * those developing custom file system implementations. Methods may be added to * this interface in future releases.

* - *

Accessing Files

+ *

Accessing Files

*

Paths may be used with the {@link Files} class to operate on files, * directories, and other types of files. For example, suppose we want a {@link * java.io.BufferedReader} to read text from a file "{@code access.log}". The @@ -75,7 +75,7 @@ import java.util.Iterator; * BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8); * * - *

Interoperability

+ *

Interoperability

*

Paths associated with the default {@link * java.nio.file.spi.FileSystemProvider provider} are generally interoperable * with the {@link java.io.File java.io.File} class. Paths created by other @@ -87,7 +87,7 @@ import java.util.Iterator; * addition, the {@link #toFile toFile} method is useful to construct a {@code * File} from the {@code String} representation of a {@code Path}. * - *

Concurrency

+ *

Concurrency

*

Implementations of this interface are immutable and safe for use by * multiple concurrent threads. * diff --git a/src/share/classes/java/nio/file/SecureDirectoryStream.java b/src/share/classes/java/nio/file/SecureDirectoryStream.java index 6ef4882ea..2bfa2056b 100644 --- a/src/share/classes/java/nio/file/SecureDirectoryStream.java +++ b/src/share/classes/java/nio/file/SecureDirectoryStream.java @@ -122,6 +122,8 @@ public interface SecureDirectoryStream * an optional list of attributes to set atomically when creating * the file * + * @return the seekable byte channel + * * @throws ClosedDirectoryStreamException * if the directory stream is closed * @throws IllegalArgumentException @@ -260,6 +262,8 @@ public interface SecureDirectoryStream * then all methods to read or update attributes will throw {@link * ClosedDirectoryStreamException ClosedDirectoryStreamException}. * + * @param + * The {@code FileAttributeView} type * @param type * the {@code Class} object corresponding to the file attribute view * @@ -288,6 +292,8 @@ public interface SecureDirectoryStream * is created but methods to read or update attributes of the file will * fail when invoked and the file does not exist. * + * @param + * The {@code FileAttributeView} type * @param path * the path of the file * @param type diff --git a/src/share/classes/java/nio/file/WatchEvent.java b/src/share/classes/java/nio/file/WatchEvent.java index cab199f0b..508486851 100644 --- a/src/share/classes/java/nio/file/WatchEvent.java +++ b/src/share/classes/java/nio/file/WatchEvent.java @@ -55,11 +55,16 @@ public interface WatchEvent { public static interface Kind { /** * Returns the name of the event kind. + * + * @return the name of the event kind */ String name(); /** * Returns the type of the {@link WatchEvent#context context} value. + * + * + * @return the type of the context value */ Class type(); } @@ -76,6 +81,8 @@ public interface WatchEvent { public static interface Modifier { /** * Returns the name of the modifier. + * + * @return the name of the modifier */ String name(); } diff --git a/src/share/classes/java/nio/file/WatchService.java b/src/share/classes/java/nio/file/WatchService.java index 5a63fcd87..c6440b208 100644 --- a/src/share/classes/java/nio/file/WatchService.java +++ b/src/share/classes/java/nio/file/WatchService.java @@ -78,7 +78,7 @@ import java.util.concurrent.TimeUnit; * The {@link java.nio.channels.FileChannel FileChannel} class defines methods * to lock regions of a file against access by other programs. * - *

Platform dependencies

+ *

Platform dependencies

* *

The implementation that observes events from the file system is intended * to map directly on to the native file event notification facility where diff --git a/src/share/classes/java/nio/file/attribute/AclEntry.java b/src/share/classes/java/nio/file/attribute/AclEntry.java index 9b4ef8a34..49bf52924 100644 --- a/src/share/classes/java/nio/file/attribute/AclEntry.java +++ b/src/share/classes/java/nio/file/attribute/AclEntry.java @@ -134,6 +134,7 @@ public final class AclEntry { /** * Sets the type component of this builder. * + * @param type the component type * @return this builder */ public Builder setType(AclEntryType type) { @@ -146,6 +147,7 @@ public final class AclEntry { /** * Sets the principal component of this builder. * + * @param who the principal component * @return this builder */ public Builder setPrincipal(UserPrincipal who) { @@ -168,6 +170,7 @@ public final class AclEntry { * Sets the permissions component of this builder. On return, the * permissions component of this builder is a copy of the given set. * + * @param perms the permissions component * @return this builder * * @throws ClassCastException @@ -193,6 +196,7 @@ public final class AclEntry { * permissions component of this builder is a copy of the permissions in * the given array. * + * @param perms the permissions component * @return this builder */ public Builder setPermissions(AclEntryPermission... perms) { @@ -211,6 +215,7 @@ public final class AclEntry { * Sets the flags component of this builder. On return, the flags * component of this builder is a copy of the given set. * + * @param flags the flags component * @return this builder * * @throws ClassCastException @@ -236,6 +241,7 @@ public final class AclEntry { * component of this builder is a copy of the flags in the given * array. * + * @param flags the flags component * @return this builder */ public Builder setFlags(AclEntryFlag... flags) { @@ -267,9 +273,7 @@ public final class AclEntry { /** * Constructs a new builder with the components of an existing ACL entry. * - * @param entry - * an ACL entry - * + * @param entry an ACL entry * @return a new builder */ public static Builder newBuilder(AclEntry entry) { @@ -278,6 +282,8 @@ public final class AclEntry { /** * Returns the ACL entry type. + * + * @return the ACL entry type */ public AclEntryType type() { return type; @@ -285,6 +291,8 @@ public final class AclEntry { /** * Returns the principal component. + * + * @return the principal component */ public UserPrincipal principal() { return who; @@ -294,6 +302,8 @@ public final class AclEntry { * Returns a copy of the permissions component. * *

The returned set is a modifiable copy of the permissions. + * + * @return the permissions component */ public Set permissions() { return new HashSet(perms); @@ -303,6 +313,8 @@ public final class AclEntry { * Returns a copy of the flags component. * *

The returned set is a modifiable copy of the flags. + * + * @return the flags component */ public Set flags() { return new HashSet(flags); diff --git a/src/share/classes/java/nio/file/attribute/AclFileAttributeView.java b/src/share/classes/java/nio/file/attribute/AclFileAttributeView.java index 2f94937b6..f5d58d41f 100644 --- a/src/share/classes/java/nio/file/attribute/AclFileAttributeView.java +++ b/src/share/classes/java/nio/file/attribute/AclFileAttributeView.java @@ -54,7 +54,7 @@ import java.io.IOException; * supportsFileAttributeView} method can be used to test if a file system * supports ACLs. * - *

Interoperability

+ *

Interoperability

* * RFC 3530 allows for special user identities to be used on platforms that * support the POSIX defined access permissions. The special user identities @@ -65,7 +65,7 @@ import java.io.IOException; * UserPrincipalLookupService} may be used to obtain a {@link UserPrincipal} * to represent these special identities by invoking the {@link * UserPrincipalLookupService#lookupPrincipalByName lookupPrincipalByName} - * method.

+ * method. * *

Usage Example: * Suppose we wish to add an entry to an existing ACL to grant "joe" access: @@ -90,11 +90,11 @@ import java.io.IOException; * view.setAcl(acl); * * - *

Dynamic Access

+ *

Dynamic Access

*

Where dynamic access to file attributes is required, the attributes * supported by this attribute view are as follows: *

- *
{@code "*"} Read all {@link BasicFileAttributes basic-file-attributes}.
+ *
* * * @@ -118,7 +118,7 @@ import java.io.IOException; * update the ACL or owner attributes as if by invoking the {@link #setAcl setAcl} * or {@link #setOwner setOwner} methods. * - *

Setting the ACL when creating a file

+ *

Setting the ACL when creating a file

* *

Implementations supporting this attribute view may also support setting * the initial ACL when creating a file or directory. The initial ACL diff --git a/src/share/classes/java/nio/file/attribute/AttributeView.java b/src/share/classes/java/nio/file/attribute/AttributeView.java index 0b2951b96..d33f9764a 100644 --- a/src/share/classes/java/nio/file/attribute/AttributeView.java +++ b/src/share/classes/java/nio/file/attribute/AttributeView.java @@ -38,6 +38,8 @@ package java.nio.file.attribute; public interface AttributeView { /** * Returns the name of the attribute view. + * + * @return the name of the attribute view */ String name(); } diff --git a/src/share/classes/java/nio/file/attribute/BasicFileAttributeView.java b/src/share/classes/java/nio/file/attribute/BasicFileAttributeView.java index 2a8e2c958..3a9c79169 100644 --- a/src/share/classes/java/nio/file/attribute/BasicFileAttributeView.java +++ b/src/share/classes/java/nio/file/attribute/BasicFileAttributeView.java @@ -41,7 +41,7 @@ import java.io.IOException; *

Where dynamic access to file attributes is required, the attributes * supported by this attribute view have the following names and types: *

- *
Name Type
+ *
* * * diff --git a/src/share/classes/java/nio/file/attribute/BasicFileAttributes.java b/src/share/classes/java/nio/file/attribute/BasicFileAttributes.java index d1f715dce..df2d10bb2 100644 --- a/src/share/classes/java/nio/file/attribute/BasicFileAttributes.java +++ b/src/share/classes/java/nio/file/attribute/BasicFileAttributes.java @@ -87,22 +87,31 @@ public interface BasicFileAttributes { /** * Tells whether the file is a regular file with opaque content. + * + * @return {@code true} if the file is a regular file with opaque content */ boolean isRegularFile(); /** * Tells whether the file is a directory. + * + * @return {@code true} if the file is a directory */ boolean isDirectory(); /** * Tells whether the file is a symbolic link. + * + * @return {@code true} if the file is a symbolic link */ boolean isSymbolicLink(); /** * Tells whether the file is something other than a regular file, directory, * or symbolic link. + * + * @return {@code true} if the file something other than a regular file, + * directory or symbolic link */ boolean isOther(); @@ -138,6 +147,8 @@ public interface BasicFileAttributes { * and two files are the {@link java.nio.file.Files#isSameFile same} with * non-{@code null} file keys, then their file keys are equal. * + * @return an object that uniquely identifies the given file, or {@code null} + * * @see java.nio.file.Files#walkFileTree */ Object fileKey(); diff --git a/src/share/classes/java/nio/file/attribute/DosFileAttributeView.java b/src/share/classes/java/nio/file/attribute/DosFileAttributeView.java index aa99d2332..1fb53853a 100644 --- a/src/share/classes/java/nio/file/attribute/DosFileAttributeView.java +++ b/src/share/classes/java/nio/file/attribute/DosFileAttributeView.java @@ -41,7 +41,7 @@ import java.io.IOException; * BasicFileAttributeView}, and in addition, the following attributes are * supported: *
- *
Name Type
+ *
* * * diff --git a/src/share/classes/java/nio/file/attribute/FileAttribute.java b/src/share/classes/java/nio/file/attribute/FileAttribute.java index d3704cbf8..461687634 100644 --- a/src/share/classes/java/nio/file/attribute/FileAttribute.java +++ b/src/share/classes/java/nio/file/attribute/FileAttribute.java @@ -40,11 +40,15 @@ package java.nio.file.attribute; public interface FileAttribute { /** * Returns the attribute name. + * + * @return The attribute name */ String name(); /** * Returns the attribute value. + * + * @return The attribute value */ T value(); } diff --git a/src/share/classes/java/nio/file/attribute/PosixFileAttributeView.java b/src/share/classes/java/nio/file/attribute/PosixFileAttributeView.java index ea5f1e2ea..81a6a4156 100644 --- a/src/share/classes/java/nio/file/attribute/PosixFileAttributeView.java +++ b/src/share/classes/java/nio/file/attribute/PosixFileAttributeView.java @@ -68,13 +68,13 @@ import java.io.IOException; * PosixFilePermissions.toString(attrs.permissions())); * * - *

Dynamic Access

+ *

Dynamic Access

*

Where dynamic access to file attributes is required, the attributes * supported by this attribute view are as defined by {@link * BasicFileAttributeView} and {@link FileOwnerAttributeView}, and in addition, * the following attributes are supported: *

- *
Name Type
+ *
* * * @@ -102,7 +102,7 @@ import java.io.IOException; * #setPermissions setPermissions}, {@link #setOwner setOwner}, and {@link * #setGroup setGroup} methods respectively. * - *

Setting Initial Permissions

+ *

Setting Initial Permissions

*

Implementations supporting this attribute view may also support setting * the initial permissions when creating a file or directory. The * initial permissions are provided to the {@link Files#createFile createFile} diff --git a/src/share/classes/java/nio/file/spi/FileSystemProvider.java b/src/share/classes/java/nio/file/spi/FileSystemProvider.java index 84e92d9cb..5b95dcc39 100644 --- a/src/share/classes/java/nio/file/spi/FileSystemProvider.java +++ b/src/share/classes/java/nio/file/spi/FileSystemProvider.java @@ -287,6 +287,8 @@ public abstract class FileSystemProvider { * @param uri * The URI to convert * + * @return The resulting {@code Path} + * * @throws IllegalArgumentException * If the URI scheme does not identify this provider or other * preconditions on the uri parameter do not hold @@ -751,6 +753,8 @@ public abstract class FileSystemProvider { * @param link * the path to the symbolic link * + * @return The target of the symbolic link + * * @throws UnsupportedOperationException * if the implementation does not support symbolic links * @throws NotLinkException @@ -984,6 +988,8 @@ public abstract class FileSystemProvider { * exactly the manner specified by the {@link Files#getFileAttributeView} * method. * + * @param + * The {@code FileAttributeView} type * @param path * the path to the file * @param type @@ -1002,6 +1008,8 @@ public abstract class FileSystemProvider { * exactly the manner specified by the {@link * Files#readAttributes(Path,Class,LinkOption[])} method. * + * @param + * The {@code BasicFileAttributes} type * @param path * the path to the file * @param type diff --git a/src/share/classes/java/sql/SQLInput.java b/src/share/classes/java/sql/SQLInput.java index ae65e67ac..b768fa95e 100644 --- a/src/share/classes/java/sql/SQLInput.java +++ b/src/share/classes/java/sql/SQLInput.java @@ -444,7 +444,7 @@ public interface SQLInput { *

* The default implementation will throw {@code SQLFeatureNotSupportedException} * - * @param the type of the class modeled by this Class object + * @param the type of the class modeled by this Class object * @param type Class representing the Java data type to convert the attribute to. * @return the attribute at the head of the stream as an {@code Object} in the * Java programming language;{@code null} if the attribute is SQL {@code NULL} -- GitLab

Name Type