8020971: Fix doclint issues in java.nio.*
authordarcy
Sat, 20 Jul 2013 11:39:39 -0700
changeset 19034 d068b8fff162
parent 19033 13013b301bd0
child 19035 129954ce8d08
8020971: Fix doclint issues in java.nio.* Reviewed-by: lancea
jdk/src/share/classes/java/nio/channels/package-info.java
jdk/src/share/classes/java/nio/charset/Charset.java
jdk/src/share/classes/java/nio/charset/MalformedInputException.java
jdk/src/share/classes/java/nio/charset/UnmappableCharacterException.java
jdk/src/share/classes/java/nio/file/package-info.java
--- a/jdk/src/share/classes/java/nio/channels/package-info.java	Fri Jul 19 09:42:58 2013 -0700
+++ b/jdk/src/share/classes/java/nio/channels/package-info.java	Sat Jul 20 11:39:39 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -31,7 +31,7 @@
  * <a name="channels"></a>
  *
  * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists channels and their descriptions">
- * <tr><th><p align="left">Channels</p></th><th><p align="left">Description</p></th></tr>
+ * <tr><th align="left">Channels</th><th align="left">Description</th></tr>
  * <tr><td valign=top><tt><i>{@link java.nio.channels.Channel}</i></tt></td>
  *     <td>A nexus for I/O operations</td></tr>
  * <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.ReadableByteChannel}</i></tt></td>
@@ -110,7 +110,7 @@
  * write them to a given writable byte channel.
  *
  * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists file channels and their descriptions">
- * <tr><th><p align="left">File channels</p></th><th><p align="left">Description</p></th></tr>
+ * <tr><th align="left">File channels</th><th align="left">Description</th></tr>
  * <tr><td valign=top><tt>{@link java.nio.channels.FileChannel}</tt></td>
  *     <td>Reads, writes, maps, and manipulates files</td></tr>
  * <tr><td valign=top><tt>{@link java.nio.channels.FileLock}</tt></td>
@@ -138,7 +138,7 @@
  *
  * <a name="multiplex"></a>
  * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists multiplexed, non-blocking channels and their descriptions">
- * <tr><th><p align="left">Multiplexed, non-blocking I/O</p></th><th><p align="left">Description</p></th></tr>
+ * <tr><th align="left">Multiplexed, non-blocking I/O</th><th align="left"><p>Description</th></tr>
  * <tr><td valign=top><tt>{@link java.nio.channels.SelectableChannel}</tt></td>
  *     <td>A channel that can be multiplexed</td></tr>
  * <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.DatagramChannel}</tt></td>
@@ -225,7 +225,7 @@
  * <a name="async"></a>
  *
  * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists asynchronous channels and their descriptions">
- * <tr><th><p align="left">Asynchronous I/O</p></th><th><p align="left">Description</p></th></tr>
+ * <tr><th align="left">Asynchronous I/O</th><th align="left">Description</th></tr>
  * <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousFileChannel}</tt></td>
  *     <td>An asynchronous channel for reading, writing, and manipulating a file</td></tr>
  * <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousSocketChannel}</tt></td>
--- a/jdk/src/share/classes/java/nio/charset/Charset.java	Fri Jul 19 09:42:58 2013 -0700
+++ b/jdk/src/share/classes/java/nio/charset/Charset.java	Sat Jul 20 11:39:39 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -65,7 +65,7 @@
  * concurrent threads.
  *
  *
- * <a name="names"><a name="charenc">
+ * <a name="names"></a><a name="charenc"></a>
  * <h2>Charset names</h2>
  *
  * <p> Charsets are named by strings composed of the following characters:
@@ -111,21 +111,17 @@
  * The aliases of a charset are returned by the {@link #aliases() aliases}
  * method.
  *
- * <a name="hn">
- *
- * <p> Some charsets have an <i>historical name</i> that is defined for
- * compatibility with previous versions of the Java platform.  A charset's
+ * <p><a name="hn">Some charsets have an <i>historical name</i> that is defined for
+ * compatibility with previous versions of the Java platform.</a>  A charset's
  * historical name is either its canonical name or one of its aliases.  The
  * historical name is returned by the <tt>getEncoding()</tt> methods of the
  * {@link java.io.InputStreamReader#getEncoding InputStreamReader} and {@link
  * java.io.OutputStreamWriter#getEncoding OutputStreamWriter} classes.
  *
- * <a name="iana">
- *
- * <p> If a charset listed in the <a
+ * <p><a name="iana">If a charset listed in the <a
  * href="http://www.iana.org/assignments/character-sets"><i>IANA Charset
  * Registry</i></a> is supported by an implementation of the Java platform then
- * its canonical name must be the name listed in the registry.  Many charsets
+ * its canonical name must be the name listed in the registry.</a>  Many charsets
  * are given more than one name in the registry, in which case the registry
  * identifies one of the names as <i>MIME-preferred</i>.  If a charset has more
  * than one registry name then its canonical name must be the MIME-preferred
@@ -142,15 +138,15 @@
  *
  * <h2>Standard charsets</h2>
  *
- * <a name="standard">
+ *
  *
- * <p> Every implementation of the Java platform is required to support the
- * following standard charsets.  Consult the release documentation for your
+ * <p><a name="standard">Every implementation of the Java platform is required to support the
+ * following standard charsets.</a>  Consult the release documentation for your
  * implementation to see if any other charsets are supported.  The behavior
  * of such optional charsets may differ between implementations.
  *
  * <blockquote><table width="80%" summary="Description of standard charsets">
- * <tr><th><p align="left">Charset</p></th><th><p align="left">Description</p></th></tr>
+ * <tr><th align="left">Charset</th><th align="left">Description</th></tr>
  * <tr><td valign=top><tt>US-ASCII</tt></td>
  *     <td>Seven-bit ASCII, a.k.a. <tt>ISO646-US</tt>,
  *         a.k.a. the Basic Latin block of the Unicode character set</td></tr>
--- a/jdk/src/share/classes/java/nio/charset/MalformedInputException.java	Fri Jul 19 09:42:58 2013 -0700
+++ b/jdk/src/share/classes/java/nio/charset/MalformedInputException.java	Sat Jul 20 11:39:39 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2007, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -42,14 +42,27 @@
 
     private int inputLength;
 
+    /**
+     * Constructs an {@code MalformedInputException} with the given
+     * length.
+     * @param inputLength the length of the input
+     */
     public MalformedInputException(int inputLength) {
         this.inputLength = inputLength;
     }
 
+    /**
+     * Returns the length of the input.
+     * @return the length of the input
+     */
     public int getInputLength() {
         return inputLength;
     }
 
+    /**
+     * Returns the message.
+     * @return the message
+     */
     public String getMessage() {
         return "Input length = " + inputLength;
     }
--- a/jdk/src/share/classes/java/nio/charset/UnmappableCharacterException.java	Fri Jul 19 09:42:58 2013 -0700
+++ b/jdk/src/share/classes/java/nio/charset/UnmappableCharacterException.java	Sat Jul 20 11:39:39 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2007, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -42,14 +42,27 @@
 
     private int inputLength;
 
+    /**
+     * Constructs an {@code UnmappableCharacterException} with the
+     * given length.
+     * @param inputLength the length of the input
+     */
     public UnmappableCharacterException(int inputLength) {
         this.inputLength = inputLength;
     }
 
+    /**
+     * Returns the length of the input.
+     * @return the length of the input
+     */
     public int getInputLength() {
         return inputLength;
     }
 
+    /**
+     * Returns the message.
+     * @return the message
+     */
     public String getMessage() {
         return "Input length = " + inputLength;
     }
--- a/jdk/src/share/classes/java/nio/file/package-info.java	Fri Jul 19 09:42:58 2013 -0700
+++ b/jdk/src/share/classes/java/nio/file/package-info.java	Sat Jul 20 11:39:39 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -33,8 +33,8 @@
  * package is used by service provider implementors wishing to extend the
  * platform default provider, or to construct other provider implementations. </p>
  *
- * <a name="links"><h3>Symbolic Links</h3></a>
- * Many operating systems and file systems support for <em>symbolic links</em>.
+ * <h3><a name="links">Symbolic Links</a></h3>
+ * <p> Many operating systems and file systems support for <em>symbolic links</em>.
  * A symbolic link is a special file that serves as a reference to another file.
  * For the most part, symbolic links are transparent to applications and
  * operations on symbolic links are automatically redirected to the <em>target</em>
@@ -45,8 +45,8 @@
  * that are semantically close but support for these other types of links is
  * not included in this package. </p>
  *
- * <a name="interop"><h3>Interoperability</h3></a>
- * The {@link java.io.File} class defines the {@link java.io.File#toPath
+ * <h3><a name="interop">Interoperability</a></h3>
+ * <p> The {@link java.io.File} class defines the {@link java.io.File#toPath
  * toPath} method to construct a {@link java.nio.file.Path} by converting
  * the abstract path represented by the {@code java.io.File} object. The resulting
  * {@code Path} can be used to operate on the same file as the {@code File}
@@ -55,7 +55,7 @@
  * and {@code java.io.File} objects. </p>
  *
  * <h3>Visibility</h3>
- * The view of the files and file system provided by classes in this package are
+ * <p> The view of the files and file system provided by classes in this package are
  * guaranteed to be consistent with other views provided by other instances in the
  * same Java virtual machine.  The view may or may not, however, be consistent with
  * the view of the file system as seen by other concurrently running programs due
@@ -65,8 +65,8 @@
  * or on some other machine.  The exact nature of any such inconsistencies are
  * system-dependent and are therefore unspecified. </p>
  *
- * <a name="integrity"><h3>Synchronized I/O File Integrity</h3></a>
- * The {@link java.nio.file.StandardOpenOption#SYNC SYNC} and {@link
+ * <h3><a name="integrity">Synchronized I/O File Integrity</a></h3>
+ * <p> The {@link java.nio.file.StandardOpenOption#SYNC SYNC} and {@link
  * java.nio.file.StandardOpenOption#DSYNC DSYNC} options are used when opening a file
  * to require that updates to the file are written synchronously to the underlying
  * storage device. In the case of the default provider, and the file resides on
@@ -83,7 +83,7 @@
  * specific. </p>
  *
  * <h3>General Exceptions</h3>
- * Unless otherwise noted, passing a {@code null} argument to a constructor
+ * <p> Unless otherwise noted, passing a {@code null} argument to a constructor
  * or method of any class or interface in this package will cause a {@link
  * java.lang.NullPointerException NullPointerException} to be thrown. Additionally,
  * invoking a method with a collection containing a {@code null} element will