Merge

make/common/Release.gmk

@@ -400,7 +400,8 @@ TOOLS = \
 # classes that go into jfr.jar
 JFR_CLASSES_DIRS= \
 	com/oracle/jrockit/jfr \
-	oracle/jrockit/jfr
+	oracle/jrockit/jfr \
+	jdk/jfr
 
 # classes that go into jsse.jar
 JSSE_CLASSES_DIRS = \
@@ -612,6 +613,7 @@ ifndef JAVASE_EMBEDDED
 	$(ECHO) "oracle/jrockit/jfr/parser/" >> $@
 	$(ECHO) "oracle/jrockit/jfr/settings/" >> $@
 	$(ECHO) "oracle/jrockit/jfr/tools/" >> $@
+	$(ECHO) "jdk/jfr/" >> $@
 endif
 endif
 

makefiles/CreateJars.gmk

@@ -246,7 +246,8 @@ RT_JAR_EXCLUDES += \
 	sun/util/resources/cldr \
 	$(LOCALEDATA_INCLUDES) \
 	com/oracle/jrockit/jfr \
-	oracle/jrockit/jfr
+	oracle/jrockit/jfr \
+	jdk/jfr
 
 ifeq ($(OPENJDK_TARGET_OS), macosx)
         RT_JAR_EXCLUDES += com/sun/nio/sctp \
@@ -428,7 +429,8 @@ ifeq ($(ENABLE_JFR), true)
 		SRCS:=$(JDK_OUTPUTDIR)/classes,\
 		SUFFIXES:=.class .jfc .xsd,\
 		INCLUDES:=com/oracle/jrockit/jfr \
-			  oracle/jrockit/jfr,\
+			  oracle/jrockit/jfr \
+			  jdk/jfr,\
 		JAR:=$(IMAGES_OUTPUTDIR)/lib/jfr.jar,\
 		SKIP_METAINF:=true,\
 		MANIFEST:=$(MAINMANIFEST), \

src/share/classes/java/nio/Buffer.java

@@ -52,7 +52,7 @@ import java.util.Spliterator;
  * <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 @@ import java.util.Spliterator;
  * 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 @@ import java.util.Spliterator;
  * {@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 @@ import java.util.Spliterator;
  * 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 @@ import java.util.Spliterator;
  * </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 @@ import java.util.Spliterator;
  * {@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

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.
  *
- * <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

src/share/classes/java/nio/X-Buffer.java.template

@@ -44,23 +44,23 @@ import java.util.stream.$Streamtype$Stream;
  *
  * <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]?,&#32;a&#32;string,} or some other $type$
  *   buffer into this buffer;{#if[!byte]?&#32;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 @@ import java.util.stream.$Streamtype$Stream;
  *
 #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&#32;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&#32;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 @@ import java.util.stream.$Streamtype$Stream;
  *
 #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 @@ import java.util.stream.$Streamtype$Stream;
  * 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 @@ import java.util.stream.$Streamtype$Stream;
  * 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 @@ import java.util.stream.$Streamtype$Stream;
  * 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 @@ import java.util.stream.$Streamtype$Stream;
 #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 @@ public abstract class $Type$Buffer
      * <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 @@ public abstract class $Type$Buffer
      *
      * <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 @@ public abstract class $Type$Buffer
      * 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 @@ 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
      * <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 @@ public abstract class $Type$Buffer
      * <pre>
      *     src.get(a, 0, a.length) </pre>
      *
+     * @param   dst
+     *          The destination array
+     *
      * @return  This buffer
      *
      * @throws  BufferUnderflowException
@@ -842,6 +844,9 @@ public abstract class $Type$Buffer
      * <pre>
      *     dst.put(a, 0, a.length) </pre>
      *
+     * @param   src
+     *          The source array
+     *
      * @return  This buffer
      *
      * @throws  BufferOverflowException
@@ -930,6 +935,9 @@ public abstract class $Type$Buffer
      * <pre>
      *     dst.put(s, 0, s.length()) </pre>
      *
+     * @param   src
+     *          The source string
+     *
      * @return  This buffer
      *
      * @throws  BufferOverflowException
@@ -1419,7 +1427,7 @@ public abstract class $Type$Buffer
      *
      * <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>

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   <A>
+     *          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   <A>
+     *          The type of the attachment
      * @param   src
      *          The buffer from which bytes are to be retrieved
      * @param   attachment

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.
  *
- * <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

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.
  *
- * <table border>
+ * <table border summary="System properties">
  *   <tr>
  *     <th>System property</th>
  *     <th>Description</th>
@@ -89,7 +89,7 @@ import java.util.concurrent.TimeUnit;
  *   </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 @@ import java.util.concurrent.TimeUnit;
  * 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;

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   <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 @@ public abstract class AsynchronousFileChannel
      *     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 @@ 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   <A>
+     *          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   <A>
+     *          The type of the attachment
      * @param   src
      *          The buffer from which bytes are to be transferred
      * @param   position

src/share/classes/java/nio/channels/AsynchronousServerSocketChannel.java

@@ -52,7 +52,7 @@ import java.io.IOException;
  * <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 @@ 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   <A>
+     *          The type of the attachment
      * @param   attachment
      *          The object to attach to the I/O operation; can be {@code null}
      * @param   handler

src/share/classes/java/nio/channels/AsynchronousSocketChannel.java

@@ -62,7 +62,7 @@ import java.nio.ByteBuffer;
  * <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 @@ import java.nio.ByteBuffer;
  * </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 @@ 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   <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 @@ public abstract class AsynchronousSocketChannel
      * 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 @@ public abstract class AsynchronousSocketChannel
      * 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 @@ public abstract class AsynchronousSocketChannel
      * 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 @@ public abstract class AsynchronousSocketChannel
      * 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

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:
  * <blockquote>
- * <table border>
+ * <table border summary="Socket options">
  *   <tr>
  *     <th>Option Name</th>
  *     <th>Description</th>
@@ -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);

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
  * <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 @@ public abstract class FileChannel
      * <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.

src/share/classes/java/nio/channels/FileLock.java

@@ -72,7 +72,7 @@ import java.io.IOException;
  * <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 @@ 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  <tt>true</tt> if, and only if, this lock and the given lock
      *          range overlap by at least one byte
      */

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.
  *
- * <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

src/share/classes/java/nio/channels/NetworkChannel.java

@@ -106,6 +106,8 @@ public interface NetworkChannel
     /**
      * 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 @@ public interface NetworkChannel
     /**
      * Returns the value of a socket option.
      *
+     * @param   <T>
+     *          The type of the socket option value
      * @param   name
      *          The socket option
      *

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.
  *
  * <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 @@ 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);

src/share/classes/java/nio/channels/SelectableChannel.java

@@ -64,8 +64,8 @@ import java.nio.channels.spi.SelectorProvider;
  * 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 @@ 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 <tt>null</tt> if this channel is not
      *          currently registered with that selector

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 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

src/share/classes/java/nio/channels/Selector.java

@@ -36,13 +36,13 @@ import java.util.Set;
  *
  * <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 @@ import java.util.Set;
  * 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 @@ 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: </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 @@ import java.util.Set;
  *     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 @@ import java.util.Set;
  * 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 @@ import java.util.Set;
  * <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

src/share/classes/java/nio/channels/ServerSocketChannel.java

@@ -46,7 +46,7 @@ import java.nio.channels.spi.SelectorProvider;
  * <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 @@ 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);

src/share/classes/java/nio/channels/SocketChannel.java

@@ -66,7 +66,7 @@ import java.nio.channels.spi.SelectorProvider;
  * <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 @@ 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

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
- * <tt>try</tt>&nbsp;...&nbsp;<tt>finally</tt> block: <a name="be">
+ * <tt>try</tt>&nbsp;...&nbsp;<tt>finally</tt> block:
  *
  * <blockquote><pre>
  * boolean completed = false;

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.
      * </p>
+     *
+     * @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.  </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
      */

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
- * <tt>try</tt>&nbsp;...&nbsp;<tt>finally</tt> block: <a name="be">
+ * <tt>try</tt>&nbsp;...&nbsp;<tt>finally</tt> block:
  *
  * <blockquote><pre>
  * 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;

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
      *

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;

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$ {
      * <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 @@ public abstract class Charset$Coder$ {
      * <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 @@ public abstract class Charset$Coder$ {
      * <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 @@ public abstract class Charset$Coder$ {
      * <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

src/share/classes/java/nio/charset/Charset.java

@@ -66,7 +66,7 @@ import sun.security.action.GetPropertyAction;
  *
  *
  * <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 @@ import sun.security.action.GetPropertyAction;
  * previous canonical name be made into an alias.
  *
  *
- * <h4>Standard charsets</h4>
+ * <h2>Standard charsets</h2>
  *
  * <a name="standard">
  *
@@ -217,7 +217,7 @@ import sun.security.action.GetPropertyAction;
  * <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&nbsp;2278</i></a>.
@@ -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  <tt>true</tt> if the given charset is contained in this charset
      */
     public abstract boolean contains(Charset cs);

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) {

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() </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

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   <V>
+     *          The {@code FileStoreAttributeView} type
      * @param   type
      *          the {@code Class} object corresponding to the attribute view
      *

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:
      *
      * <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>

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

src/share/classes/java/nio/file/Files.java

@@ -194,7 +194,7 @@ public final class Files {
      * <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 @@ public final class Files {
      *     }
      * </pre>
      *
-     *
+     * @param   <V>
+     *          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);
      * </pre>
      *
+     * @param   <A>
+     *          The {@code BasicFileAttributes} type
      * @param   path
      *          the path to the file
      * @param   type
@@ -1863,7 +1866,7 @@ public final class Files {
      * 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 @@ 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 {
      * </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 @@ 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

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. </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 @@ import java.util.Iterator;
  *     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 @@ 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}.
  *
- * <h4>Concurrency</h4>
+ * <h2>Concurrency</h2>
  * <p> Implementations of this interface are immutable and safe for use by
  * multiple concurrent threads.
  *

src/share/classes/java/nio/file/SecureDirectoryStream.java

@@ -122,6 +122,8 @@ public interface SecureDirectoryStream<T>
      *          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<T>
      * 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 @@ public interface SecureDirectoryStream<T>
      * 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

src/share/classes/java/nio/file/WatchEvent.java

@@ -55,11 +55,16 @@ public interface WatchEvent<T> {
     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 interface WatchEvent<T> {
     public static interface Modifier {
         /**
          * Returns the name of the modifier.
+         *
+         * @return the name of the modifier
          */
         String name();
     }

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.
  *
- * <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

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.
      *
      * <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 @@ public final class AclEntry {
      * 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);

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.
  *
- * <a name="interop"><h4>Interoperability</h4></a>
+ * <h2>Interoperability</h2>
  *
  * RFC&nbsp;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. </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 @@ import java.io.IOException;
  *     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 @@ import java.io.IOException;
  * 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

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();
 }

src/share/classes/java/nio/file/attribute/BasicFileAttributeView.java

@@ -41,7 +41,7 @@ import java.io.IOException;
  * <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>

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();

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:
  * <blockquote>
- * <table border="1" cellpadding="8">
+ * <table border="1" cellpadding="8" summary="Supported attributes">
  *   <tr>
  *     <th> Name </th>
  *     <th> Type </th>

src/share/classes/java/nio/file/attribute/FileAttribute.java

@@ -40,11 +40,15 @@ package java.nio.file.attribute;
 public interface FileAttribute<T> {
     /**
      * Returns the attribute name.
+     *
+     * @return The attribute name
      */
     String name();
 
     /**
      * Returns the attribute value.
+     *
+     * @return The attribute value
      */
     T value();
 }

src/share/classes/java/nio/file/attribute/PosixFileAttributeView.java

@@ -68,13 +68,13 @@ import java.io.IOException;
  *         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 @@ import java.io.IOException;
  * #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}

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   <V>
+     *          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   <A>
+     *          The {@code BasicFileAttributes} type
      * @param   path
      *          the path to the file
      * @param   type

src/share/classes/java/sql/SQLInput.java

@@ -444,7 +444,7 @@ public interface SQLInput {
      *<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}