8019380: doclint warnings in java.nio, java.nio.file.**, java.nio.channels.**
Reviewed-by: chegar
--- a/jdk/src/share/classes/java/nio/Buffer.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/Buffer.java Fri Jun 28 16:10:23 2013 +0100
@@ -52,7 +52,7 @@
* <p> There is one subclass of this class for each non-boolean primitive type.
*
*
- * <h4> Transferring data </h4>
+ * <h2> Transferring data </h2>
*
* <p> Each subclass of this class defines two categories of <i>get</i> and
* <i>put</i> operations: </p>
@@ -78,7 +78,7 @@
* current position.
*
*
- * <h4> Marking and resetting </h4>
+ * <h2> Marking and resetting </h2>
*
* <p> A buffer's <i>mark</i> 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 @@
* {@link InvalidMarkException} to be thrown.
*
*
- * <h4> Invariants </h4>
+ * <h2> Invariants </h2>
*
* <p> The following invariant holds for the mark, position, limit, and
* capacity values:
@@ -109,7 +109,7 @@
* to zero.
*
*
- * <h4> Clearing, flipping, and rewinding </h4>
+ * <h2> Clearing, flipping, and rewinding </h2>
*
* <p> 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 @@
* </ul>
*
*
- * <h4> Read-only buffers </h4>
+ * <h2> Read-only buffers </h2>
*
* <p> Every buffer is readable, but not every buffer is writable. The
* mutation methods of each buffer class are specified as <i>optional
@@ -143,14 +143,14 @@
* {@link #isReadOnly isReadOnly} method.
*
*
- * <h4> Thread safety </h4>
+ * <h2> Thread safety </h2>
*
* <p> 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.
*
*
- * <h4> Invocation chaining </h4>
+ * <h2> Invocation chaining </h2>
*
* <p> 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
--- a/jdk/src/share/classes/java/nio/MappedByteBuffer.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/MappedByteBuffer.java Fri Jun 28 16:10:23 2013 +0100
@@ -45,7 +45,7 @@
* this program or another. Whether or not such changes occur, and when they
* occur, is operating-system dependent and therefore unspecified.
*
- * <a name="inaccess"><p> All or part of a mapped byte buffer may become
+ * <a name="inaccess"></a><p> 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
--- a/jdk/src/share/classes/java/nio/X-Buffer.java.template Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/X-Buffer.java.template Fri Jun 28 16:10:23 2013 +0100
@@ -44,23 +44,23 @@
*
* <ul>
*
- * <li><p> Absolute and relative {@link #get() </code><i>get</i><code>} and
- * {@link #put($type$) </code><i>put</i><code>} methods that read and write
+ * <li><p> Absolute and relative {@link #get() <i>get</i>} and
+ * {@link #put($type$) <i>put</i>} methods that read and write
* single $type$s; </p></li>
*
- * <li><p> Relative {@link #get($type$[]) </code><i>bulk get</i><code>}
+ * <li><p> Relative {@link #get($type$[]) <i>bulk get</i>}
* methods that transfer contiguous sequences of $type$s from this buffer
* into an array; {#if[!byte]?and}</p></li>
*
- * <li><p> Relative {@link #put($type$[]) </code><i>bulk put</i><code>}
+ * <li><p> Relative {@link #put($type$[]) <i>bulk put</i>}
* methods that transfer contiguous sequences of $type$s from $a$
* $type$ array{#if[char]?, a string,} or some other $type$
* buffer into this buffer;{#if[!byte]? and} </p></li>
*
#if[byte]
*
- * <li><p> Absolute and relative {@link #getChar() </code><i>get</i><code>}
- * and {@link #putChar(char) </code><i>put</i><code>} methods that read and
+ * <li><p> Absolute and relative {@link #getChar() <i>get</i>}
+ * and {@link #putChar(char) <i>put</i>} methods that read and
* write values of other primitive types, translating them to and from
* sequences of bytes in a particular byte order; </p></li>
*
@@ -70,23 +70,23 @@
*
#end[byte]
*
- * <li><p> Methods for {@link #compact </code>compacting<code>}, {@link
- * #duplicate </code>duplicating<code>}, and {@link #slice
- * </code>slicing<code>} $a$ $type$ buffer. </p></li>
+ * <li><p> Methods for {@link #compact compacting}, {@link
+ * #duplicate duplicating}, and {@link #slice slicing}
+ * $a$ $type$ buffer. </p></li>
*
* </ul>
*
* <p> $Type$ buffers can be created either by {@link #allocate
- * </code><i>allocation</i><code>}, which allocates space for the buffer's
+ * <i>allocation</i>}, which allocates space for the buffer's
*
#if[byte]
*
- * content, or by {@link #wrap($type$[]) </code><i>wrapping</i><code>} an
+ * content, or by {@link #wrap($type$[]) <i>wrapping</i>} an
* existing $type$ array {#if[char]?or string} into a buffer.
*
#else[byte]
*
- * content, by {@link #wrap($type$[]) </code><i>wrapping</i><code>} an existing
+ * content, by {@link #wrap($type$[]) <i>wrapping</i>} an existing
* $type$ array {#if[char]?or string} into a buffer, or by creating a
* <a href="ByteBuffer.html#views"><i>view</i></a> of an existing byte buffer.
*
@@ -94,8 +94,8 @@
*
#if[byte]
*
- * <a name="direct">
- * <h4> Direct <i>vs.</i> non-direct buffers </h4>
+ * <a name="direct"></a>
+ * <h2> Direct <i>vs.</i> non-direct buffers </h2>
*
* <p> A byte buffer is either <i>direct</i> or <i>non-direct</i>. Given a
* direct byte buffer, the Java virtual machine will make a best effort to
@@ -116,7 +116,7 @@
* buffers only when they yield a measureable gain in program performance.
*
* <p> A direct byte buffer may also be created by {@link
- * java.nio.channels.FileChannel#map </code>mapping<code>} 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 @@
* that explicit buffer management can be done in performance-critical code.
*
*
- * <a name="bin">
- * <h4> Access to binary data </h4>
+ * <a name="bin"></a>
+ * <h2> Access to binary data </h2>
*
* <p> This class defines methods for reading and writing values of all other
* primitive types, except <tt>boolean</tt>. Primitive values are translated
@@ -156,7 +156,7 @@
* parameters of the absolute <i>get</i> and <i>put</i> methods are in terms of
* bytes rather than of the type being read or written.
*
- * <a name="views">
+ * <a name="views"></a>
*
* <p> For access to homogeneous binary data, that is, sequences of values of
* the same type, this class defines methods that can create <i>views</i> of a
@@ -214,7 +214,7 @@
#end[char]
*
#if[byte]
- * <h4> Invocation chaining </h4>
+ * <h2> Invocation chaining </h2>
#end[byte]
*
* <p> Methods in this class that do not otherwise have a value to return are
@@ -297,7 +297,7 @@
* <p> 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 </code>backing array<code>} is unspecified.
+ * {@link #hasArray backing array} is unspecified.
*
* @param capacity
* The new buffer's capacity, in $type$s
@@ -318,9 +318,8 @@
*
* <p> 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
- * </code>backing array<code>}, and its {@link #arrayOffset </code>array
- * offset<code>} 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 @@
* and vice versa. The new buffer's capacity will be
* <tt>array.length</tt>, its position will be <tt>offset</tt>, its limit
* will be <tt>offset + length</tt>, and its mark will be undefined. Its
- * {@link #array </code>backing array<code>} will be the given array, and
- * its {@link #arrayOffset </code>array offset<code>} will be zero. </p>
+ * {@link #array backing array} will be the given array, and
+ * its {@link #arrayOffset array offset} will be zero. </p>
*
* @param array
* The array that will back the new buffer
@@ -384,8 +383,8 @@
* 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
* <tt>array.length</tt>, its position will be zero, and its mark will be
- * undefined. Its {@link #array </code>backing array<code>} will be the
- * given array, and its {@link #arrayOffset </code>array offset<code>} will
+ * undefined. Its {@link #array backing array} will be the
+ * given array, and its {@link #arrayOffset array offset>} will
* be zero. </p>
*
* @param array
@@ -703,6 +702,9 @@
* <pre>
* src.get(a, 0, a.length) </pre>
*
+ * @param dst
+ * The destination array
+ *
* @return This buffer
*
* @throws BufferUnderflowException
@@ -842,6 +844,9 @@
* <pre>
* dst.put(a, 0, a.length) </pre>
*
+ * @param src
+ * The source array
+ *
* @return This buffer
*
* @throws BufferOverflowException
@@ -930,6 +935,9 @@
* <pre>
* dst.put(s, 0, s.length()) </pre>
*
+ * @param src
+ * The source string
+ *
* @return This buffer
*
* @throws BufferOverflowException
@@ -1419,7 +1427,7 @@
*
* <p> The byte order of $a$ $type$ buffer created by allocation or by
* wrapping an existing <tt>$type$</tt> array is the {@link
- * ByteOrder#nativeOrder </code>native order<code>} of the underlying
+ * ByteOrder#nativeOrder native order} of the underlying
* hardware. The byte order of $a$ $type$ buffer created as a <a
* href="ByteBuffer.html#views">view</a> of a byte buffer is that of the
* byte buffer at the moment that the view is created. </p>
--- a/jdk/src/share/classes/java/nio/channels/AsynchronousByteChannel.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/AsynchronousByteChannel.java Fri Jun 28 16:10:23 2013 +0100
@@ -87,6 +87,8 @@
* initiates a read operation before a previous read operation has
* completed then a {@link ReadPendingException} will be thrown.
*
+ * @param <A>
+ * The type of the attachment
* @param dst
* The buffer into which bytes are to be transferred
* @param attachment
@@ -166,6 +168,8 @@
* initiates a write operation before a previous write operation has
* completed then a {@link WritePendingException} will be thrown.
*
+ * @param <A>
+ * The type of the attachment
* @param src
* The buffer from which bytes are to be retrieved
* @param attachment
--- a/jdk/src/share/classes/java/nio/channels/AsynchronousChannel.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/AsynchronousChannel.java Fri Jun 28 16:10:23 2013 +0100
@@ -61,7 +61,7 @@
* may not allow more than one read and one write operation to be outstanding at
* any given time.
*
- * <h4>Cancellation</h4>
+ * <h2>Cancellation</h2>
*
* <p> The {@code Future} interface defines the {@link Future#cancel cancel}
* method to cancel execution. This causes all threads waiting on the result of
--- a/jdk/src/share/classes/java/nio/channels/AsynchronousChannelGroup.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/AsynchronousChannelGroup.java Fri Jun 28 16:10:23 2013 +0100
@@ -60,7 +60,7 @@
* default group is not configured then the pooled threads of the default group
* are {@link Thread#isDaemon daemon} threads.
*
- * <table border>
+ * <table border summary="System properties">
* <tr>
* <th>System property</th>
* <th>Description</th>
@@ -89,7 +89,7 @@
* </tr>
* </table>
*
- * <a name="threading"><h4>Threading</h4></a>
+ * <a name="threading"></a><h2>Threading</h2>
*
* <p> 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 @@
* handler directly by the initiating thread (see {@link
* AsynchronousServerSocketChannel#accept(Object,CompletionHandler) accept}).
*
- * <a name="shutdown"><h4>Shutdown and Termination</h4></a>
+ * <a name="shutdown"></a><h2>Shutdown and Termination</h2>
*
* <p> The {@link #shutdown() shutdown} method is used to initiate an <em>orderly
* shutdown</em> of a group. An orderly shutdown marks the group as shutdown;
--- a/jdk/src/share/classes/java/nio/channels/AsynchronousFileChannel.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/AsynchronousFileChannel.java Fri Jun 28 16:10:23 2013 +0100
@@ -425,6 +425,8 @@
* They are not suitable for controlling access to a file by multiple
* threads within the same virtual machine.
*
+ * @param <A>
+ * 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 @@
* ch.{@link #lock(long,long,boolean,Object,CompletionHandler) lock}(0L, Long.MAX_VALUE, false, att, handler)
* </pre>
*
+ * @param <A>
+ * 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 @@
* 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 <A>
+ * The type of the attachment
* @param dst
* The buffer into which bytes are to be transferred
* @param position
@@ -716,6 +722,8 @@
* bytes; the values of any bytes between the previous end-of-file and the
* newly-written bytes are unspecified.
*
+ * @param <A>
+ * The type of the attachment
* @param src
* The buffer from which bytes are to be transferred
* @param position
--- a/jdk/src/share/classes/java/nio/channels/AsynchronousServerSocketChannel.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/AsynchronousServerSocketChannel.java Fri Jun 28 16:10:23 2013 +0100
@@ -52,7 +52,7 @@
* <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
* setOption} method. Channels of this type support the following options:
* <blockquote>
- * <table border>
+ * <table border summary="Socket options">
* <tr>
* <th>Option Name</th>
* <th>Description</th>
@@ -98,6 +98,9 @@
/**
* 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 @@
/**
* Returns the provider that created this channel.
+ *
+ * @return The provider that created this channel
*/
public final AsynchronousChannelProvider provider() {
return provider;
@@ -263,6 +268,8 @@
* the connection is closed and the operation completes with a {@link
* SecurityException}.
*
+ * @param <A>
+ * The type of the attachment
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
--- a/jdk/src/share/classes/java/nio/channels/AsynchronousSocketChannel.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/AsynchronousSocketChannel.java Fri Jun 28 16:10:23 2013 +0100
@@ -62,7 +62,7 @@
* <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
* setOption} method. Asynchronous socket channels support the following options:
* <blockquote>
- * <table border>
+ * <table border summary="Socket options">
* <tr>
* <th>Option Name</th>
* <th>Description</th>
@@ -91,7 +91,7 @@
* </blockquote>
* Additional (implementation specific) options may also be supported.
*
- * <h4>Timeouts</h4>
+ * <h2>Timeouts</h2>
*
* <p> The {@link #read(ByteBuffer,long,TimeUnit,Object,CompletionHandler) read}
* and {@link #write(ByteBuffer,long,TimeUnit,Object,CompletionHandler) write}
@@ -123,6 +123,9 @@
/**
* 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 @@
/**
* Returns the provider that created this channel.
+ *
+ * @return The provider that created this channel
*/
public final AsynchronousChannelProvider provider() {
return provider;
@@ -287,6 +292,8 @@
* java.lang.SecurityManager#checkConnect checkConnect} method permits
* connecting to the address and port number of the given remote endpoint.
*
+ * @param <A>
+ * The type of the attachment
* @param remote
* The remote address to which this channel is to be connected
* @param attachment
@@ -365,6 +372,8 @@
* AsynchronousByteChannel#read(ByteBuffer,Object,CompletionHandler)}
* method.
*
+ * @param <A>
+ * The type of the attachment
* @param dst
* The buffer into which bytes are to be transferred
* @param timeout
@@ -461,6 +470,8 @@
* read from the channel will cause an unspecific runtime exception to be
* thrown.
*
+ * @param <A>
+ * The type of the attachment
* @param dsts
* The buffers into which bytes are to be transferred
* @param offset
@@ -520,6 +531,8 @@
* AsynchronousByteChannel#write(ByteBuffer,Object,CompletionHandler)}
* method.
*
+ * @param <A>
+ * The type of the attachment
* @param src
* The buffer from which bytes are to be retrieved
* @param timeout
@@ -610,6 +623,8 @@
* to write to the channel will cause an unspecific runtime exception to be
* thrown.
*
+ * @param <A>
+ * The type of the attachment
* @param srcs
* The buffers from which bytes are to be retrieved
* @param offset
--- a/jdk/src/share/classes/java/nio/channels/DatagramChannel.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/DatagramChannel.java Fri Jun 28 16:10:23 2013 +0100
@@ -57,7 +57,7 @@
* setOption} method. A datagram channel to an Internet Protocol socket supports
* the following options:
* <blockquote>
- * <table border>
+ * <table border summary="Socket options">
* <tr>
* <th>Option Name</th>
* <th>Description</th>
@@ -117,6 +117,9 @@
/**
* Initializes a new instance of this class.
+ *
+ * @param provider
+ * The provider that created this channel
*/
protected DatagramChannel(SelectorProvider provider) {
super(provider);
--- a/jdk/src/share/classes/java/nio/channels/FileChannel.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/FileChannel.java Fri Jun 28 16:10:23 2013 +0100
@@ -46,7 +46,7 @@
* of bytes that can be read and written and whose current {@link #size
* <i>size</i>} 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 </code><i>truncated</i><code>}. The
+ * decreases when it is {@link #truncate <i>truncated</i>}. The
* file may also have some associated <i>metadata</i> such as access
* permissions, content type, and last-modification time; this class does not
* define methods for metadata access.
@@ -830,7 +830,7 @@
* <p> A region of a file may be mapped into memory in one of three modes:
* </p>
*
- * <ul type=disc>
+ * <ul>
*
* <li><p> <i>Read-only:</i> Any attempt to modify the resulting buffer
* will cause a {@link java.nio.ReadOnlyBufferException} to be thrown.
--- a/jdk/src/share/classes/java/nio/channels/FileLock.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/FileLock.java Fri Jun 28 16:10:23 2013 +0100
@@ -72,7 +72,7 @@
* <p> File-lock objects are safe for use by multiple concurrent threads.
*
*
- * <a name="pdep"><h4> Platform dependencies </h4></a>
+ * <a name="pdep"></a><h2> Platform dependencies </h2>
*
* <p> 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 @@
/**
* 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 <tt>true</tt> if, and only if, this lock and the given lock
* range overlap by at least one byte
*/
--- a/jdk/src/share/classes/java/nio/channels/MulticastChannel.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/MulticastChannel.java Fri Jun 28 16:10:23 2013 +0100
@@ -71,7 +71,7 @@
* MembershipKey#drop drop} method drops membership so that datagrams from the
* source address can no longer be received.
*
- * <h4>Platform dependencies</h4>
+ * <h2>Platform dependencies</h2>
*
* The multicast implementation is intended to map directly to the native
* multicasting facility. Consequently, the following items should be considered
--- a/jdk/src/share/classes/java/nio/channels/NetworkChannel.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/NetworkChannel.java Fri Jun 28 16:10:23 2013 +0100
@@ -106,6 +106,8 @@
/**
* Sets the value of a socket option.
*
+ * @param <T>
+ * The type of the socket option value
* @param name
* The socket option
* @param value
@@ -130,6 +132,8 @@
/**
* Returns the value of a socket option.
*
+ * @param <T>
+ * The type of the socket option value
* @param name
* The socket option
*
--- a/jdk/src/share/classes/java/nio/channels/Pipe.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/Pipe.java Fri Jun 28 16:10:23 2013 +0100
@@ -33,10 +33,9 @@
* A pair of channels that implements a unidirectional pipe.
*
* <p> A pipe consists of a pair of channels: A writable {@link
- * Pipe.SinkChannel </code>sink<code>} channel and a readable {@link
- * Pipe.SourceChannel </code>source<code>} 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.
*
* <p> 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 @@
{
/**
* Constructs a new instance of this class.
+ *
+ * @param provider
+ * The selector provider
*/
protected SourceChannel(SelectorProvider provider) {
super(provider);
@@ -94,6 +96,9 @@
{
/**
* Initializes a new instance of this class.
+ *
+ * @param provider
+ * The selector provider
*/
protected SinkChannel(SelectorProvider provider) {
super(provider);
--- a/jdk/src/share/classes/java/nio/channels/SelectableChannel.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/SelectableChannel.java Fri Jun 28 16:10:23 2013 +0100
@@ -64,8 +64,8 @@
* threads. </p>
*
*
- * <a name="bm">
- * <h4>Blocking mode</h4>
+ * <a name="bm"></a>
+ * <h2>Blocking mode</h2>
*
* A selectable channel is either in <i>blocking</i> mode or in
* <i>non-blocking</i> mode. In blocking mode, every I/O operation invoked
@@ -142,6 +142,9 @@
* 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 <tt>null</tt> if this channel is not
* currently registered with that selector
--- a/jdk/src/share/classes/java/nio/channels/SelectionKey.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/SelectionKey.java Fri Jun 28 16:10:23 2013 +0100
@@ -42,7 +42,7 @@
* next selection operation. The validity of a key may be tested by invoking
* its {@link #isValid isValid} method.
*
- * <a name="opsets">
+ * <a name="opsets"></a>
*
* <p> A selection key contains two <i>operation sets</i> represented as
* integer values. Each bit of an operation set denotes a category of
--- a/jdk/src/share/classes/java/nio/channels/Selector.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/Selector.java Fri Jun 28 16:10:23 2013 +0100
@@ -36,13 +36,13 @@
*
* <p> 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 </code>selector provider<code>} 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 name="ks">
+ * <a name="ks"></a>
*
* <p> 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 @@
* during the next selection operation, at which time the key will removed from
* all of the selector's key sets.
*
- * <a name="sks"><p> Keys are added to the selected-key set by selection
+ * <a name="sks"></a><p> 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 </code>iterator<code>} 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. </p>
*
*
- * <a name="selop">
- * <h4>Selection</h4>
+ * <a name="selop"></a>
+ * <h2>Selection</h2>
*
* <p> 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 @@
* operation began. For a channel that is ready for at least one such
* operation, one of the following two actions is performed: </p>
*
- * <ol type=a>
+ * <ol>
*
* <li><p> 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 @@
* words, the ready set returned by the underlying system is
* bitwise-disjoined into the key's current ready set. </p></li>
*
- * </ol></li>
+ * </ol>
*
* 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 @@
* difference between the three selection methods. </p>
*
*
- * <h4>Concurrency</h4>
+ * <h2>Concurrency</h2>
*
* <p> Selectors are themselves safe for use by multiple concurrent threads;
* their key sets, however, are not.
@@ -183,7 +183,7 @@
* <p> The {@link #close close} method synchronizes on the selector and all
* three key sets in the same order as in a selection operation.
*
- * <a name="ksc">
+ * <a name="ksc"></a>
*
* <p> 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
--- a/jdk/src/share/classes/java/nio/channels/ServerSocketChannel.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/ServerSocketChannel.java Fri Jun 28 16:10:23 2013 +0100
@@ -46,7 +46,7 @@
* <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
* setOption} method. Server-socket channels support the following options:
* <blockquote>
- * <table border>
+ * <table border summary="Socket options">
* <tr>
* <th>Option Name</th>
* <th>Description</th>
@@ -78,6 +78,9 @@
/**
* Initializes a new instance of this class.
+ *
+ * @param provider
+ * The provider that created this channel
*/
protected ServerSocketChannel(SelectorProvider provider) {
super(provider);
--- a/jdk/src/share/classes/java/nio/channels/SocketChannel.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/SocketChannel.java Fri Jun 28 16:10:23 2013 +0100
@@ -66,7 +66,7 @@
* <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
* setOption} method. Socket channels support the following options:
* <blockquote>
- * <table border>
+ * <table border summary="Socket options">
* <tr>
* <th>Option Name</th>
* <th>Description</th>
@@ -120,6 +120,9 @@
/**
* 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 @@
* @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
--- a/jdk/src/share/classes/java/nio/channels/spi/AbstractInterruptibleChannel.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/spi/AbstractInterruptibleChannel.java Fri Jun 28 16:10:23 2013 +0100
@@ -46,7 +46,7 @@
* 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
- * <tt>try</tt> ... <tt>finally</tt> block: <a name="be">
+ * <tt>try</tt> ... <tt>finally</tt> block:
*
* <blockquote><pre>
* boolean completed = false;
--- a/jdk/src/share/classes/java/nio/channels/spi/AbstractSelectableChannel.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/spi/AbstractSelectableChannel.java Fri Jun 28 16:10:23 2013 +0100
@@ -72,6 +72,9 @@
/**
* 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 @@
* that is blocked in an I/O operation upon this channel to return
* immediately, either by throwing an exception or by returning normally.
* </p>
+ *
+ * @throws IOException
+ * If an I/O error occurs
*/
protected abstract void implCloseSelectableChannel() throws IOException;
@@ -299,6 +305,10 @@
* changing the blocking mode. This method is only invoked if the new mode
* is different from the current mode. </p>
*
+ * @param block If <tt>true</tt> then this channel will be placed in
+ * blocking mode; if <tt>false</tt> then it will be placed
+ * non-blocking mode
+ *
* @throws IOException
* If an I/O error occurs
*/
--- a/jdk/src/share/classes/java/nio/channels/spi/AbstractSelector.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/spi/AbstractSelector.java Fri Jun 28 16:10:23 2013 +0100
@@ -43,7 +43,7 @@
* 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
- * <tt>try</tt> ... <tt>finally</tt> block: <a name="be">
+ * <tt>try</tt> ... <tt>finally</tt> block:
*
* <blockquote><pre>
* try {
@@ -77,6 +77,9 @@
/**
* Initializes a new instance of this class.
+ *
+ * @param provider
+ * The provider that created this selector
*/
protected AbstractSelector(SelectorProvider provider) {
this.provider = provider;
--- a/jdk/src/share/classes/java/nio/channels/spi/AsynchronousChannelProvider.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/spi/AsynchronousChannelProvider.java Fri Jun 28 16:10:23 2013 +0100
@@ -174,6 +174,8 @@
* @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 @@
* 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
*
--- a/jdk/src/share/classes/java/nio/channels/spi/SelectorProvider.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/channels/spi/SelectorProvider.java Fri Jun 28 16:10:23 2013 +0100
@@ -183,6 +183,9 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* Opens a socket channel.
*
* @return The new channel
+ *
+ * @throws IOException
+ * If an I/O error occurs
*/
public abstract SocketChannel openSocketChannel()
throws IOException;
--- a/jdk/src/share/classes/java/nio/charset/Charset-X-Coder.java.template Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/charset/Charset-X-Coder.java.template Fri Jun 28 16:10:23 2013 +0100
@@ -163,6 +163,9 @@
* 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 @@
* $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 @@
* <p> 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. </p>
+ *
+ * @param newAction The new action
*/
protected void implOnMalformedInput(CodingErrorAction newAction) { }
@@ -428,6 +436,8 @@
* <p> 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. </p>
+ *
+ * @param newAction The new action
*/
protected void implOnUnmappableCharacter(CodingErrorAction newAction) { }
@@ -925,6 +935,9 @@
* <p> The default implementation of this method is not very efficient; it
* should generally be overridden to improve performance. </p>
*
+ * @param c
+ * The given character
+ *
* @return <tt>true</tt> if, and only if, this encoder can encode
* the given character
*
@@ -953,6 +966,9 @@
* <p> The default implementation of this method is not very efficient; it
* should generally be overridden to improve performance. </p>
*
+ * @param cs
+ * The given character sequence
+ *
* @return <tt>true</tt> if, and only if, this encoder can encode
* the given character without throwing any exceptions and without
* performing any replacements
--- a/jdk/src/share/classes/java/nio/charset/Charset.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/charset/Charset.java Fri Jun 28 16:10:23 2013 +0100
@@ -66,7 +66,7 @@
*
*
* <a name="names"><a name="charenc">
- * <h4>Charset names</h4>
+ * <h2>Charset names</h2>
*
* <p> Charsets are named by strings composed of the following characters:
*
@@ -140,7 +140,7 @@
* previous canonical name be made into an alias.
*
*
- * <h4>Standard charsets</h4>
+ * <h2>Standard charsets</h2>
*
* <a name="standard">
*
@@ -217,7 +217,7 @@
* <p>The {@link StandardCharsets} class defines constants for each of the
* standard charsets.
*
- * <h4>Terminology</h4>
+ * <h2>Terminology</h2>
*
* <p> The name of this class is taken from the terms used in
* <a href="http://www.ietf.org/rfc/rfc2278.txt"><i>RFC 2278</i></a>.
@@ -737,6 +737,9 @@
* it is not necessarily the case that the given charset is not contained
* in this charset.
*
+ * @param cs
+ * The given charset
+ *
* @return <tt>true</tt> if the given charset is contained in this charset
*/
public abstract boolean contains(Charset cs);
--- a/jdk/src/share/classes/java/nio/charset/CoderResult.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/charset/CoderResult.java Fri Jun 28 16:10:23 2013 +0100
@@ -227,6 +227,9 @@
* 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 @@
* 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) {
--- a/jdk/src/share/classes/java/nio/charset/spi/CharsetProvider.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/charset/spi/CharsetProvider.java Fri Jun 28 16:10:23 2013 +0100
@@ -39,8 +39,8 @@
* 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() </code>context
- * class loader<code>}.
+ * thread's {@link java.lang.Thread#getContextClassLoader() context class
+ * loader}.
*
* <p> A charset provider identifies itself with a provider-configuration file
* named <tt>java.nio.charset.spi.CharsetProvider</tt> in the resource
--- a/jdk/src/share/classes/java/nio/file/FileStore.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/FileStore.java Fri Jun 28 16:10:23 2013 +0100
@@ -173,6 +173,8 @@
* The {@code type} parameter is the type of the attribute view required and
* the method returns an instance of that type if supported.
*
+ * @param <V>
+ * The {@code FileStoreAttributeView} type
* @param type
* the {@code Class} object corresponding to the attribute view
*
--- a/jdk/src/share/classes/java/nio/file/FileSystem.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/FileSystem.java Fri Jun 28 16:10:23 2013 +0100
@@ -315,7 +315,7 @@
* that resembles regular expressions but with a simpler syntax. For example:
*
* <blockquote>
- * <table border="0">
+ * <table border="0" summary="Pattern Language">
* <tr>
* <td>{@code *.java}</td>
* <td>Matches a path that represents a file name ending in {@code .java}</td>
--- a/jdk/src/share/classes/java/nio/file/FileSystems.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/FileSystems.java Fri Jun 28 16:10:23 2013 +0100
@@ -200,6 +200,10 @@
* 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
--- a/jdk/src/share/classes/java/nio/file/Files.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/Files.java Fri Jun 28 16:10:23 2013 +0100
@@ -194,7 +194,7 @@
* <p> In the addition to {@code READ} and {@code WRITE}, the following
* options may be present:
*
- * <table border=1 cellpadding=5 summary="">
+ * <table border=1 cellpadding=5 summary="Options">
* <tr> <th>Option</th> <th>Description</th> </tr>
* <tr>
* <td> {@link StandardOpenOption#APPEND APPEND} </td>
@@ -1616,7 +1616,8 @@
* }
* </pre>
*
- *
+ * @param <V>
+ * The {@code FileAttributeView} type
* @param path
* the path to the file
* @param type
@@ -1665,6 +1666,8 @@
* PosixFileAttributes attrs = Files.readAttributes(path, PosixFileAttributes.class, NOFOLLOW_LINKS);
* </pre>
*
+ * @param <A>
+ * The {@code BasicFileAttributes} type
* @param path
* the path to the file
* @param type
@@ -1863,7 +1866,7 @@
* attributes} parameter:
*
* <blockquote>
- * <table border="0">
+ * <table border="0" summary="Possible values">
* <tr>
* <td> {@code "*"} </td>
* <td> Read all {@link BasicFileAttributes basic-file-attributes}. </td>
@@ -1971,10 +1974,12 @@
* 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 @@
* 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 @@
* </pre>
*
* @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 @@
* 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 @@
* @param time
* the new last modified time
*
- * @return the file
+ * @return the path
*
* @throws IOException
* if an I/O error occurs
--- a/jdk/src/share/classes/java/nio/file/Path.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/Path.java Fri Jun 28 16:10:23 2013 +0100
@@ -64,7 +64,7 @@
* those developing custom file system implementations. Methods may be added to
* this interface in future releases. </p>
*
- * <h4>Accessing Files</h4>
+ * <h2>Accessing Files</h2>
* <p> 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 @@
* BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8);
* </pre>
*
- * <a name="interop"><h4>Interoperability</h4></a>
+ * <a name="interop"></a><h2>Interoperability</h2>
* <p> 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 @@
* addition, the {@link #toFile toFile} method is useful to construct a {@code
* File} from the {@code String} representation of a {@code Path}.
*
- * <h4>Concurrency</h4>
+ * <h2>Concurrency</h2>
* <p> Implementations of this interface are immutable and safe for use by
* multiple concurrent threads.
*
--- a/jdk/src/share/classes/java/nio/file/SecureDirectoryStream.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/SecureDirectoryStream.java Fri Jun 28 16:10:23 2013 +0100
@@ -122,6 +122,8 @@
* 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 @@
* then all methods to read or update attributes will throw {@link
* ClosedDirectoryStreamException ClosedDirectoryStreamException}.
*
+ * @param <V>
+ * The {@code FileAttributeView} type
* @param type
* the {@code Class} object corresponding to the file attribute view
*
@@ -288,6 +292,8 @@
* is created but methods to read or update attributes of the file will
* fail when invoked and the file does not exist.
*
+ * @param <V>
+ * The {@code FileAttributeView} type
* @param path
* the path of the file
* @param type
--- a/jdk/src/share/classes/java/nio/file/WatchEvent.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/WatchEvent.java Fri Jun 28 16:10:23 2013 +0100
@@ -55,11 +55,16 @@
public static interface Kind<T> {
/**
* 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<T> type();
}
@@ -76,6 +81,8 @@
public static interface Modifier {
/**
* Returns the name of the modifier.
+ *
+ * @return the name of the modifier
*/
String name();
}
--- a/jdk/src/share/classes/java/nio/file/WatchService.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/WatchService.java Fri Jun 28 16:10:23 2013 +0100
@@ -78,7 +78,7 @@
* The {@link java.nio.channels.FileChannel FileChannel} class defines methods
* to lock regions of a file against access by other programs.
*
- * <h4>Platform dependencies</h4>
+ * <h2>Platform dependencies</h2>
*
* <p> The implementation that observes events from the file system is intended
* to map directly on to the native file event notification facility where
--- a/jdk/src/share/classes/java/nio/file/attribute/AclEntry.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/attribute/AclEntry.java Fri Jun 28 16:10:23 2013 +0100
@@ -134,6 +134,7 @@
/**
* Sets the type component of this builder.
*
+ * @param type the component type
* @return this builder
*/
public Builder setType(AclEntryType type) {
@@ -146,6 +147,7 @@
/**
* Sets the principal component of this builder.
*
+ * @param who the principal component
* @return this builder
*/
public Builder setPrincipal(UserPrincipal who) {
@@ -168,6 +170,7 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
/**
* 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 @@
/**
* Returns the ACL entry type.
+ *
+ * @return the ACL entry type
*/
public AclEntryType type() {
return type;
@@ -285,6 +291,8 @@
/**
* Returns the principal component.
+ *
+ * @return the principal component
*/
public UserPrincipal principal() {
return who;
@@ -294,6 +302,8 @@
* Returns a copy of the permissions component.
*
* <p> The returned set is a modifiable copy of the permissions.
+ *
+ * @return the permissions component
*/
public Set<AclEntryPermission> permissions() {
return new HashSet<AclEntryPermission>(perms);
@@ -303,6 +313,8 @@
* Returns a copy of the flags component.
*
* <p> The returned set is a modifiable copy of the flags.
+ *
+ * @return the flags component
*/
public Set<AclEntryFlag> flags() {
return new HashSet<AclEntryFlag>(flags);
--- a/jdk/src/share/classes/java/nio/file/attribute/AclFileAttributeView.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/attribute/AclFileAttributeView.java Fri Jun 28 16:10:23 2013 +0100
@@ -54,7 +54,7 @@
* supportsFileAttributeView} method can be used to test if a file system
* supports ACLs.
*
- * <a name="interop"><h4>Interoperability</h4></a>
+ * <h2>Interoperability</h2>
*
* 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 @@
* UserPrincipalLookupService} may be used to obtain a {@link UserPrincipal}
* to represent these special identities by invoking the {@link
* UserPrincipalLookupService#lookupPrincipalByName lookupPrincipalByName}
- * method. </p>
+ * method.
*
* <p> <b>Usage Example:</b>
* Suppose we wish to add an entry to an existing ACL to grant "joe" access:
@@ -90,11 +90,11 @@
* view.setAcl(acl);
* </pre>
*
- * <h4> Dynamic Access </h4>
+ * <h2> Dynamic Access </h2>
* <p> Where dynamic access to file attributes is required, the attributes
* supported by this attribute view are as follows:
* <blockquote>
- * <table border="1" cellpadding="8">
+ * <table border="1" cellpadding="8" summary="Supported attributes">
* <tr>
* <th> Name </th>
* <th> Type </th>
@@ -118,7 +118,7 @@
* update the ACL or owner attributes as if by invoking the {@link #setAcl setAcl}
* or {@link #setOwner setOwner} methods.
*
- * <h4> Setting the ACL when creating a file </h4>
+ * <h2> Setting the ACL when creating a file </h2>
*
* <p> Implementations supporting this attribute view may also support setting
* the initial ACL when creating a file or directory. The initial ACL
--- a/jdk/src/share/classes/java/nio/file/attribute/AttributeView.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/attribute/AttributeView.java Fri Jun 28 16:10:23 2013 +0100
@@ -38,6 +38,8 @@
public interface AttributeView {
/**
* Returns the name of the attribute view.
+ *
+ * @return the name of the attribute view
*/
String name();
}
--- a/jdk/src/share/classes/java/nio/file/attribute/BasicFileAttributeView.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/attribute/BasicFileAttributeView.java Fri Jun 28 16:10:23 2013 +0100
@@ -41,7 +41,7 @@
* <p> Where dynamic access to file attributes is required, the attributes
* supported by this attribute view have the following names and types:
* <blockquote>
- * <table border="1" cellpadding="8">
+ * <table border="1" cellpadding="8" summary="Supported attributes">
* <tr>
* <th> Name </th>
* <th> Type </th>
--- a/jdk/src/share/classes/java/nio/file/attribute/BasicFileAttributes.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/attribute/BasicFileAttributes.java Fri Jun 28 16:10:23 2013 +0100
@@ -87,22 +87,31 @@
/**
* 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 @@
* 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();
--- a/jdk/src/share/classes/java/nio/file/attribute/DosFileAttributeView.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/attribute/DosFileAttributeView.java Fri Jun 28 16:10:23 2013 +0100
@@ -41,7 +41,7 @@
* BasicFileAttributeView}, and in addition, the following attributes are
* supported:
* <blockquote>
- * <table border="1" cellpadding="8">
+ * <table border="1" cellpadding="8" summary="Supported attributes">
* <tr>
* <th> Name </th>
* <th> Type </th>
--- a/jdk/src/share/classes/java/nio/file/attribute/FileAttribute.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/attribute/FileAttribute.java Fri Jun 28 16:10:23 2013 +0100
@@ -40,11 +40,15 @@
public interface FileAttribute<T> {
/**
* Returns the attribute name.
+ *
+ * @return The attribute name
*/
String name();
/**
* Returns the attribute value.
+ *
+ * @return The attribute value
*/
T value();
}
--- a/jdk/src/share/classes/java/nio/file/attribute/PosixFileAttributeView.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/attribute/PosixFileAttributeView.java Fri Jun 28 16:10:23 2013 +0100
@@ -68,13 +68,13 @@
* PosixFilePermissions.toString(attrs.permissions()));
* </pre>
*
- * <h4> Dynamic Access </h4>
+ * <h2> Dynamic Access </h2>
* <p> 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:
* <blockquote>
- * <table border="1" cellpadding="8">
+ * <table border="1" cellpadding="8" summary="Supported attributes">
* <tr>
* <th> Name </th>
* <th> Type </th>
@@ -102,7 +102,7 @@
* #setPermissions setPermissions}, {@link #setOwner setOwner}, and {@link
* #setGroup setGroup} methods respectively.
*
- * <h4> Setting Initial Permissions </h4>
+ * <h2> Setting Initial Permissions </h2>
* <p> 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}
--- a/jdk/src/share/classes/java/nio/file/spi/FileSystemProvider.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/nio/file/spi/FileSystemProvider.java Fri Jun 28 16:10:23 2013 +0100
@@ -287,6 +287,8 @@
* @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 @@
* @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 @@
* exactly the manner specified by the {@link Files#getFileAttributeView}
* method.
*
+ * @param <V>
+ * The {@code FileAttributeView} type
* @param path
* the path to the file
* @param type
@@ -1002,6 +1008,8 @@
* exactly the manner specified by the {@link
* Files#readAttributes(Path,Class,LinkOption[])} method.
*
+ * @param <A>
+ * The {@code BasicFileAttributes} type
* @param path
* the path to the file
* @param type
--- a/jdk/src/share/classes/java/sql/SQLInput.java Wed Jun 26 19:15:34 2013 +0200
+++ b/jdk/src/share/classes/java/sql/SQLInput.java Fri Jun 28 16:10:23 2013 +0100
@@ -444,7 +444,7 @@
*<p>
* The default implementation will throw {@code SQLFeatureNotSupportedException}
*
- * @param<T> the type of the class modeled by this Class object
+ * @param <T> 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}