6809132: (file) Javadoc style and consistency issues

Reviewed-by: vinnie
Contributed-by: cquinn@google.com

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

@@ -46,7 +46,7 @@ public class AccessDeniedException
      * Constructs an instance of this class.
      *
      * @param   file
-     *          A string identifying the file or {@code null} if not known.
+     *          a string identifying the file or {@code null} if not known
      */
     public AccessDeniedException(String file) {
         super(file);
@@ -56,11 +56,11 @@ public class AccessDeniedException
      * Constructs an instance of this class.
      *
      * @param   file
-     *          A string identifying the file or {@code null} if not known.
+     *          a string identifying the file or {@code null} if not known
      * @param   other
-     *          A string identifying the other file or {@code null} if not known.
+     *          a string identifying the other file or {@code null} if not known
      * @param   reason
-     *          A reason message with additional information or {@code null}
+     *          a reason message with additional information or {@code null}
      */
     public AccessDeniedException(String file, String other, String reason) {
         super(file, other, reason);

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

@@ -41,11 +41,11 @@ public class AtomicMoveNotSupportedException
      * Constructs an instance of this class.
      *
      * @param   source
-     *          A string identifying the source file or {@code null} if not known.
+     *          a string identifying the source file or {@code null} if not known
      * @param   target
-     *          A string identifying the target file or {@code null} if not known.
+     *          a string identifying the target file or {@code null} if not known
      * @param   reason
-     *          A reason message with additional information
+     *          a reason message with additional information
      */
     public AtomicMoveNotSupportedException(String source,
                                            String target,

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

@@ -41,7 +41,7 @@ public class DirectoryNotEmptyException
      * Constructs an instance of this class.
      *
      * @param   dir
-     *          A string identifying the directory or {@code null} if not known.
+     *          a string identifying the directory or {@code null} if not known
      */
     public DirectoryNotEmptyException(String dir) {
         super(dir);

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

@@ -59,9 +59,9 @@ import java.io.Closeable;
  * with cause {@link ClosedDirectoryStreamException}.
  *
  * <p> A directory stream is not required to be <i>asynchronously closeable</i>.
- * If a thread is blocked on the directory stream's iterator, reading from the
- * directory, and another thread invokes the {@code close} method then it may
- * require to block until the read operation is complete.
+ * If a thread is blocked on the directory stream's iterator reading from the
+ * directory, and another thread invokes the {@code close} method, then the
+ * second thread may block until the read operation is complete.
  *
  * <p> The {@link Iterator#hasNext() hasNext} and {@link Iterator#next() next}
  * methods can encounter an I/O error when iterating over the directory in which
@@ -108,7 +108,7 @@ public interface DirectoryStream<T>
      * create filters for a number of common usages and also methods to combine
      * filters.
      *
-     * @param   <T>     The type of the directory entry
+     * @param   <T>     the type of the directory entry
      *
      * @since 1.7
      */
@@ -117,7 +117,7 @@ public interface DirectoryStream<T>
          * Decides if the given directory entry should be accepted or filtered.
          *
          * @param   entry
-         *          The directory entry to be tested
+         *          the directory entry to be tested
          *
          * @return  {@code true} if the directory entry should be accepted
          */
@@ -127,10 +127,10 @@ public interface DirectoryStream<T>
     /**
      * Returns the iterator associated with this {@code DirectoryStream}.
      *
-     * @return  The iterator associated with this {@code DirectoryStream}
+     * @return  the iterator associated with this {@code DirectoryStream}
      *
      * @throws  IllegalStateException
-     *          If this directory stream is closed or the iterator has already
+     *          if this directory stream is closed or the iterator has already
      *          been returned
      */
     @Override

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

@@ -78,12 +78,12 @@ public final class DirectoryStreamFilters {
      * </pre>
      *
      * @param   type
-     *          The content type
+     *          the content type
      *
-     * @return  A new directory stream filter
+     * @return  a new directory stream filter
      *
      * @throws  IllegalArgumentException
-     *          If the {@code type} parameter cannot be parsed as a MIME type
+     *          if the {@code type} parameter cannot be parsed as a MIME type
      *          or it has parameters
      */
     public static <T extends FileRef> DirectoryStream.Filter<T>
@@ -128,9 +128,9 @@ public final class DirectoryStreamFilters {
      * </pre>
      *
      * @param   filters
-     *          The sequence of filters
+     *          the sequence of filters
      *
-     * @return  The resulting filter
+     * @return  the resulting filter
      */
     public static <T> DirectoryStream.Filter<T>
         allOf(final Iterable<? extends DirectoryStream.Filter<? super T>> filters)
@@ -162,9 +162,9 @@ public final class DirectoryStreamFilters {
      * entries.
      *
      * @param   filters
-     *          The sequence of filters
+     *          the sequence of filters
      *
-     * @return  The resulting filter
+     * @return  the resulting filter
      */
     public static <T> DirectoryStream.Filter<T>
         anyOf(final Iterable<? extends DirectoryStream.Filter<? super T>> filters)
@@ -191,9 +191,9 @@ public final class DirectoryStreamFilters {
      * by the given filter.
      *
      * @param   filter
-     *          The given filter
+     *          the given filter
      *
-     * @return  The resulting filter that is the complement of the given filter
+     * @return  the resulting filter that is the complement of the given filter
      */
     public static <T> DirectoryStream.Filter<T>
         complementOf(final DirectoryStream.Filter<T> filter)

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

@@ -45,7 +45,7 @@ import java.io.IOException;
  *     });
  * </pre>
  *
- * @param   <T>     The type of file reference
+ * @param   <T>     the type of file reference
  *
  * @since 1.7
  */
@@ -55,10 +55,10 @@ public interface FileAction<T extends FileRef> {
      * Invoked for a file.
      *
      * @param   file
-     *          The file
+     *          the file
      *
      * @throws  IOException
-     *          If the block terminates due an uncaught I/O exception
+     *          if the block terminates due an uncaught I/O exception
      */
     void invoke(T file) throws IOException;
 }

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

@@ -41,7 +41,7 @@ public class FileAlreadyExistsException
      * Constructs an instance of this class.
      *
      * @param   file
-     *          A string identifying the file or {@code null} if not known.
+     *          a string identifying the file or {@code null} if not known
      */
     public FileAlreadyExistsException(String file) {
         super(file);
@@ -51,11 +51,11 @@ public class FileAlreadyExistsException
      * Constructs an instance of this class.
      *
      * @param   file
-     *          A string identifying the file or {@code null} if not known.
+     *          a string identifying the file or {@code null} if not known
      * @param   other
-     *          A string identifying the other file or {@code null} if not known.
+     *          a string identifying the other file or {@code null} if not known
      * @param   reason
-     *          A reason message with additional information or {@code null}
+     *          a reason message with additional information or {@code null}
      */
     public FileAlreadyExistsException(String file, String other, String reason) {
         super(file, other, reason);

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

@@ -61,7 +61,7 @@ public abstract class FileStore {
      * <p> The string returned by this method may differ from the string
      * returned by the {@link Object#toString() toString} method.
      *
-     * @return  The name of this file store
+     * @return  the name of this file store
      */
     public abstract String name();
 
@@ -71,7 +71,7 @@ public abstract class FileStore {
      * indicate, for example, the format used or if the file store is local
      * or remote.
      *
-     * @return  A string representing the type of this file store
+     * @return  a string representing the type of this file store
      */
     public abstract String type();
 
@@ -96,7 +96,7 @@ public abstract class FileStore {
      * this are implementation specific and therefore unspecified.
      *
      * @param   type
-     *          The file attribute view type
+     *          the file attribute view type
      *
      * @return  {@code true} if, and only if, the file attribute view is
      *          supported
@@ -115,7 +115,7 @@ public abstract class FileStore {
      * specific and therefore unspecified.
      *
      * @param   name
-     *          The {@link FileAttributeView#name name} of file attribute view
+     *          the {@link FileAttributeView#name name} of file attribute view
      *
      * @return  {@code true} if, and only if, the file attribute view is
      *          supported
@@ -137,9 +137,9 @@ public abstract class FileStore {
      * always return an instance of that class.
      *
      * @param   type
-     *          The {@code Class} object corresponding to the attribute view
+     *          the {@code Class} object corresponding to the attribute view
      *
-     * @return  A file store attribute view of the specified type or
+     * @return  a file store attribute view of the specified type or
      *          {@code null} if the attribute view is not available
      */
     public abstract <V extends FileStoreAttributeView> V
@@ -160,9 +160,9 @@ public abstract class FileStore {
      * of that class.
      *
      * @param   name
-     *          The name of the attribute view
+     *          the name of the attribute view
      *
-     * @return  A file store attribute view of the given name, or {@code null}
+     * @return  a file store attribute view of the given name, or {@code null}
      *          if the attribute view is not available
      */
     public abstract FileStoreAttributeView getFileStoreAttributeView(String name);

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

@@ -45,7 +45,7 @@ public class FileSystemAlreadyExistsException
      * Constructs an instance of this class.
      *
      * @param   msg
-     *          The detail message
+     *          the detail message
      */
     public FileSystemAlreadyExistsException(String msg) {
         super(msg);

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

@@ -48,7 +48,7 @@ public class FileSystemException
      * information to explain the reason.
      *
      * @param   file
-     *          A string identifying the file or {@code null} if not known.
+     *          a string identifying the file or {@code null} if not known.
      */
     public FileSystemException(String file) {
         super((String)null);
@@ -62,12 +62,12 @@ public class FileSystemException
      * information to explain the reason.
      *
      * @param   file
-     *          A string identifying the file or {@code null} if not known.
+     *          a string identifying the file or {@code null} if not known.
      * @param   other
-     *          A string identifying the other file or {@code null} if there
+     *          a string identifying the other file or {@code null} if there
      *          isn't another file or if not known
      * @param   reason
-     *          A reason message with additional information or {@code null}
+     *          a reason message with additional information or {@code null}
      */
     public FileSystemException(String file, String other, String reason) {
         super(reason);
@@ -78,7 +78,7 @@ public class FileSystemException
     /**
      * Returns the file used to create this exception.
      *
-     * @return  The file (can be {@code null})
+     * @return  the file (can be {@code null})
      */
     public String getFile() {
         return file;
@@ -87,7 +87,7 @@ public class FileSystemException
     /**
      * Returns the other file used to create this exception.
      *
-     * @return  The other file (can be {@code null})
+     * @return  the other file (can be {@code null})
      */
     public String getOtherFile() {
         return other;
@@ -96,7 +96,7 @@ public class FileSystemException
     /**
      * Returns the string explaining why the file system operation failed.
      *
-     * @return  The string explaining why the file system operation failed
+     * @return  the string explaining why the file system operation failed
      */
     public String getReason() {
         return super.getMessage();

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

@@ -44,7 +44,7 @@ public class FileSystemNotFoundException
      * Constructs an instance of this class.
      *
      * @param   msg
-     *          The detail message
+     *          the detail message
      */
     public FileSystemNotFoundException(String msg) {
         super(msg);

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

@@ -201,14 +201,14 @@ public final class FileSystems {
      * default} file system, no permission check is required.
      *
      * @throws  IllegalArgumentException
-     *          If the pre-conditions for the {@code uri} parameter aren't met
+     *          if the pre-conditions for the {@code uri} parameter are not met
      * @throws  FileSystemNotFoundException
-     *          If the file system, identified by the URI, does not exist
+     *          if the file system, identified by the URI, does not exist
      * @throws  ProviderNotFoundException
-     *          If a provider supporting the URI scheme is not installed
+     *          if a provider supporting the URI scheme is not installed
      * @throws  SecurityException
-     *          If a security manager is installed and it denies an unspecified
-     *          permission.
+     *          if a security manager is installed and it denies an unspecified
+     *          permission
      */
     public static FileSystem getFileSystem(URI uri) {
         String scheme = uri.getScheme();
@@ -245,25 +245,25 @@ public final class FileSystems {
      * </pre>
      *
      * @param   uri
-     *          The URI identifying the file system
+     *          the URI identifying the file system
      * @param   env
-     *          A map of provider specific properties to configure the file system;
+     *          a map of provider specific properties to configure the file system;
      *          may be empty
      *
-     * @return  A new file system
+     * @return  a new file system
      *
      * @throws  IllegalArgumentException
-     *          If the pre-conditions for the {@code uri} parameter aren't met,
+     *          if the pre-conditions for the {@code uri} parameter are not met,
      *          or the {@code env} parameter does not contain properties required
      *          by the provider, or a property value is invalid
      * @throws  FileSystemAlreadyExistsException
-     *          If the file system has already been created
+     *          if the file system has already been created
      * @throws  ProviderNotFoundException
-     *          If a provider supporting the URI scheme is not installed
+     *          if a provider supporting the URI scheme is not installed
      * @throws  IOException
-     *          An I/O error occurs creating the file system
+     *          if an I/O error occurs creating the file system
      * @throws  SecurityException
-     *          If a security manager is installed and it denies an unspecified
+     *          if a security manager is installed and it denies an unspecified
      *          permission required by the file system provider implementation
      */
     public static FileSystem newFileSystem(URI uri, Map<String,?> env)
@@ -284,31 +284,31 @@ public final class FileSystems {
      * invoked to construct the new file system.
      *
      * @param   uri
-     *          The URI identifying the file system
+     *          the URI identifying the file system
      * @param   env
-     *          A map of provider specific properties to configure the file system;
+     *          a map of provider specific properties to configure the file system;
      *          may be empty
      * @param   loader
-     *          The class loader to locate the provider or {@code null} to only
+     *          the class loader to locate the provider or {@code null} to only
      *          attempt to locate an installed provider
      *
-     * @return  A new file system
+     * @return  a new file system
      *
      * @throws  IllegalArgumentException
-     *          If the pre-conditions for the {@code uri} parameter aren't met,
+     *          if the pre-conditions for the {@code uri} parameter are not met,
      *          or the {@code env} parameter does not contain properties required
      *          by the provider, or a property value is invalid
      * @throws  FileSystemAlreadyExistsException
-     *          If the URI scheme identifies an installed provider and the file
+     *          if the URI scheme identifies an installed provider and the file
      *          system has already been created
      * @throws  ProviderNotFoundException
-     *          If a provider supporting the URI scheme is not found
+     *          if a provider supporting the URI scheme is not found
      * @throws  ServiceConfigurationError
-     *          When an error occurs while loading a service provider
+     *          when an error occurs while loading a service provider
      * @throws  IOException
-     *          An I/O error occurs creating the file system
+     *          an I/O error occurs creating the file system
      * @throws  SecurityException
-     *          If a security manager is installed and it denies an unspecified
+     *          if a security manager is installed and it denies an unspecified
      *          permission required by the file system provider implementation
      */
     public static FileSystem newFileSystem(URI uri, Map<String,?> env, ClassLoader loader)
@@ -357,28 +357,28 @@ public final class FileSystems {
      * terminates and the file system is returned.
      *
      * @param   file
-     *          A reference to a file
+     *          a reference to a file
      * @param   env
-     *          A map of provider specific properties to configure the file system;
+     *          a map of provider specific properties to configure the file system;
      *          may be empty
      * @param   loader
-     *          The class loader to locate the provider or {@code null} to only
+     *          the class loader to locate the provider or {@code null} to only
      *          attempt to locate an installed provider
      *
-     * @return  A new file system
+     * @return  a new file system
      *
      * @throws  IllegalArgumentException
-     *          If the {@code env} parameter does not contain properties required
+     *          if the {@code env} parameter does not contain properties required
      *          by the provider, or a property value is invalid
      * @throws  ProviderNotFoundException
-     *          If a provider supporting this file type cannot be located
+     *          if a provider supporting this file type cannot be located
      * @throws  ServiceConfigurationError
-     *          When an error occurs while loading a service provider
+     *          when an error occurs while loading a service provider
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
-     *          If a security manager is installed and it denies an unspecified
-     *          permission.
+     *          if a security manager is installed and it denies an unspecified
+     *          permission
      */
     public static FileSystem newFileSystem(FileRef file,
                                            Map<String,?> env,

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

@@ -112,7 +112,7 @@ public interface FileVisitor<T extends FileRef> {
      * directory (and any descendants) will not be visited.
      *
      * @param   dir
-     *          A reference to the directory
+     *          a reference to the directory
      *
      * @return  the visit result
      */
@@ -122,9 +122,9 @@ public interface FileVisitor<T extends FileRef> {
      * Invoked for a directory that could not be opened.
      *
      * @param   dir
-     *          A reference to the directory
+     *          a reference to the directory
      * @param   exc
-     *          The I/O exception thrown from the attempt to open the directory
+     *          the I/O exception thrown from the attempt to open the directory
      *
      * @return  the visit result
      */
@@ -134,9 +134,9 @@ public interface FileVisitor<T extends FileRef> {
      * Invoked for a file in a directory.
      *
      * @param   file
-     *          A reference to the file
+     *          a reference to the file
      * @param   attrs
-     *          The file's basic attributes
+     *          the file's basic attributes
      *
      * @return  the visit result
      */
@@ -146,9 +146,9 @@ public interface FileVisitor<T extends FileRef> {
      * Invoked for a file when its basic file attributes could not be read.
      *
      * @param   file
-     *          A reference to the file
+     *          a reference to the file
      * @param   exc
-     *          The I/O exception thrown from the attempt to read the file
+     *          the I/O exception thrown from the attempt to read the file
      *          attributes
      *
      * @return  the visit result
@@ -163,7 +163,7 @@ public interface FileVisitor<T extends FileRef> {
      * or an I/O error when iterating over the directory).
      *
      * @param   dir
-     *          A reference to the directory
+     *          a reference to the directory
      * @param   exc
      *          {@code null} if the iteration of the directory completes without
      *          an error; otherwise the I/O exception that caused the iteration

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

@@ -43,16 +43,16 @@ public class InvalidPathException
      * Constructs an instance from the given input string, reason, and error
      * index.
      *
-     * @param  input   The input string
-     * @param  reason  A string explaining why the input was rejected
-     * @param  index   The index at which the error occurred,
+     * @param  input   the input string
+     * @param  reason  a string explaining why the input was rejected
+     * @param  index   the index at which the error occurred,
      *                 or <tt>-1</tt> if the index is not known
      *
      * @throws  NullPointerException
-     *          If either the input or reason strings are <tt>null</tt>
+     *          if either the input or reason strings are <tt>null</tt>
      *
      * @throws  IllegalArgumentException
-     *          If the error index is less than <tt>-1</tt>
+     *          if the error index is less than <tt>-1</tt>
      */
     public InvalidPathException(String input, String reason, int index) {
         super(reason);
@@ -68,11 +68,11 @@ public class InvalidPathException
      * Constructs an instance from the given input string and reason.  The
      * resulting object will have an error index of <tt>-1</tt>.
      *
-     * @param  input   The input string
-     * @param  reason  A string explaining why the input was rejected
+     * @param  input   the input string
+     * @param  reason  a string explaining why the input was rejected
      *
      * @throws  NullPointerException
-     *          If either the input or reason strings are <tt>null</tt>
+     *          if either the input or reason strings are <tt>null</tt>
      */
     public InvalidPathException(String input, String reason) {
         this(input, reason, -1);
@@ -81,7 +81,7 @@ public class InvalidPathException
     /**
      * Returns the input string.
      *
-     * @return  The input string
+     * @return  the input string
      */
     public String getInput() {
         return input;
@@ -90,7 +90,7 @@ public class InvalidPathException
     /**
      * Returns a string explaining why the input string was rejected.
      *
-     * @return  The reason string
+     * @return  the reason string
      */
     public String getReason() {
         return super.getMessage();
@@ -100,7 +100,7 @@ public class InvalidPathException
      * Returns an index into the input string of the position at which the
      * error occurred, or <tt>-1</tt> if this position is not known.
      *
-     * @return  The error index
+     * @return  the error index
      */
     public int getIndex() {
         return index;
@@ -114,7 +114,7 @@ public class InvalidPathException
      * decimal, is inserted after the reason string and before the colon
      * character.
      *
-     * @return  A string describing the error
+     * @return  a string describing the error
      */
     public String getMessage() {
         StringBuffer sb = new StringBuffer();

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

@@ -75,10 +75,10 @@ public final class LinkPermission extends BasicPermission {
      * Constructs a {@code LinkPermission} with the specified name.
      *
      * @param   name
-     *          The name of the permission. It must be "hard" or "symbolic".
+     *          the name of the permission. It must be "hard" or "symbolic".
      *
      * @throws  IllegalArgumentException
-     *          If name is empty or invalid.
+     *          if name is empty or invalid
      */
     public LinkPermission(String name) {
         super(name);
@@ -89,13 +89,13 @@ public final class LinkPermission extends BasicPermission {
      * Constructs a {@code LinkPermission} with the specified name.
      *
      * @param   name
-     *          The name of the permission; must be "hard" or "symbolic".
+     *          the name of the permission; must be "hard" or "symbolic".
      * @param   actions
-     *          The actions for the permission; must be the empty string or
+     *          the actions for the permission; must be the empty string or
      *          {@code null}
      *
      * @throws  IllegalArgumentException
-     *          If name is empty or invalid.
+     *          if name is empty or invalid
      */
     public LinkPermission(String name, String actions) {
         super(name);

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

@@ -41,7 +41,7 @@ public class NoSuchFileException
      * Constructs an instance of this class.
      *
      * @param   file
-     *          A string identifying the file or {@code null} if not known.
+     *          a string identifying the file or {@code null} if not known.
      */
     public NoSuchFileException(String file) {
         super(file);
@@ -51,11 +51,11 @@ public class NoSuchFileException
      * Constructs an instance of this class.
      *
      * @param   file
-     *          A string identifying the file or {@code null} if not known.
+     *          a string identifying the file or {@code null} if not known.
      * @param   other
-     *          A string identifying the other file or {@code null} if not known.
+     *          a string identifying the other file or {@code null} if not known.
      * @param   reason
-     *          A reason message with additional information or {@code null}
+     *          a reason message with additional information or {@code null}
      */
     public NoSuchFileException(String file, String other, String reason) {
         super(file, other, reason);

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

@@ -41,7 +41,7 @@ public class NotDirectoryException
      * Constructs an instance of this class.
      *
      * @param   file
-     *          A string identifying the file or {@code null} if not known.
+     *          a string identifying the file or {@code null} if not known
      */
     public NotDirectoryException(String file) {
         super(file);

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

@@ -41,7 +41,7 @@ public class NotLinkException
      * Constructs an instance of this class.
      *
      * @param   file
-     *          A string identifying the file or {@code null} if not known.
+     *          a string identifying the file or {@code null} if not known
      */
     public NotLinkException(String file) {
         super(file);
@@ -51,11 +51,11 @@ public class NotLinkException
      * Constructs an instance of this class.
      *
      * @param   file
-     *          A string identifying the file or {@code null} if not known.
+     *          a string identifying the file or {@code null} if not known
      * @param   other
-     *          A string identifying the other file or {@code null} if not known.
+     *          a string identifying the other file or {@code null} if not known
      * @param   reason
-     *          A reason message with additional information or {@code null}
+     *          a reason message with additional information or {@code null}
      */
     public NotLinkException(String file, String other, String reason) {
         super(file, other, reason);

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

@@ -40,7 +40,7 @@ public interface PathMatcher {
      * Tells if given path matches this matcher's pattern.
      *
      * @param   path
-     *          The path to match
+     *          the path to match
      *
      * @return  {@code true} if, and only if, the path matches this
      *          matcher's pattern

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

@@ -45,13 +45,23 @@ public class Paths {
      * getPath} method of the {@link FileSystems#getDefault default} {@link
      * FileSystem}.
      *
+     * <p> Note that while this method is very convenient, using it will
+     * imply an assumed reference to the default FileSystem and limit the
+     * utility of the calling code. Hence it should not be used in library code
+     * intended for flexible reuse. A more flexible alternative is to use an
+     * existing {@code Path} instance as an anchor, such as:
+     * <pre>
+     *     Path dir = ...
+     *     Path path = dir.resolve("file");
+     * </pre>
+     *
      * @param   path
-     *          The path string to convert
+     *          the path string to convert
      *
-     * @return  The resulting {@code Path}
+     * @return  the resulting {@code Path}
      *
      * @throws  InvalidPathException
-     *          If the path string cannot be converted to a {@code Path}
+     *          if the path string cannot be converted to a {@code Path}
      *
      * @see FileSystem#getPath
      */
@@ -88,18 +98,18 @@ public class Paths {
      * provider specific and therefore unspecified.
      *
      * @param   uri
-     *          The URI to convert
+     *          the URI to convert
      *
-     * @return  The resulting {@code Path}
+     * @return  the resulting {@code Path}
      *
      * @throws  IllegalArgumentException
-     *          If preconditions on the {@code uri} parameter do not hold. The
+     *          if preconditions on the {@code uri} parameter do not hold. The
      *          format of the URI is provider specific.
      * @throws  FileSystemNotFoundException
-     *          If the file system identified by the URI does not exist or the
+     *          if the file system identified by the URI does not exist or the
      *          provider identified by the URI's scheme component is not installed
      * @throws  SecurityException
-     *          If a security manager is installed and it denies an unspecified
+     *          if a security manager is installed and it denies an unspecified
      *          permission to access the file system
      */
     public static Path get(URI uri) {

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

@@ -45,7 +45,7 @@ public class ProviderMismatchException
      * Constructs an instance of this class.
      *
      * @param   msg
-     *          The detail message
+     *          the detail message
      */
     public ProviderMismatchException(String msg) {
         super(msg);

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

@@ -44,7 +44,7 @@ public class ProviderNotFoundException
      * Constructs an instance of this class.
      *
      * @param   msg
-     *          The detail message
+     *          the detail message
      */
     public ProviderNotFoundException(String msg) {
         super(msg);

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

@@ -91,21 +91,21 @@ public abstract class SecureDirectoryStream
      * effect upon newly created directory stream.
      *
      * @param   path
-     *          The path to the directory to open
+     *          the path to the directory to open
      * @param   followLinks
      *          {@code true} if the links should be followed
      * @param   filter
-     *          The directory stream filter or {@code null}.
+     *          the directory stream filter or {@code null}.
      *
-     * @return  A new and open {@code SecureDirectoryStream} object
+     * @return  a new and open {@code SecureDirectoryStream} object
      *
      * @throws  ClosedDirectoryStreamException
-     *          If the directory stream is closed
+     *          if the directory stream is closed
      * @throws  NotDirectoryException
-     *          If the file could not otherwise be opened because it is not
+     *          if the file could not otherwise be opened because it is not
      *          a directory <i>(optional specific exception)</i>
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default provider, and a security manager is
      *          installed, the {@link SecurityManager#checkRead(String) checkRead}
@@ -134,26 +134,26 @@ public abstract class SecureDirectoryStream
      * channel.
      *
      * @param   path
-     *          The path of the file to open open or create
+     *          the path of the file to open open or create
      * @param   options
-     *          Options specifying how the file is opened
+     *          options specifying how the file is opened
      * @param   attrs
-     *          An optional list of attributes to set atomically when creating
+     *          an optional list of attributes to set atomically when creating
      *          the file
      *
      * @throws  ClosedDirectoryStreamException
-     *          If the directory stream is closed
+     *          if the directory stream is closed
      * @throws  IllegalArgumentException
-     *          If the set contains an invalid combination of options
+     *          if the set contains an invalid combination of options
      * @throws  UnsupportedOperationException
-     *          If an unsupported open option is specified or the array contains
+     *          if an unsupported open option is specified or the array contains
      *          attributes that cannot be set atomically when creating the file
      * @throws  FileAlreadyExistsException
-     *          If a file of that name already exists and the {@link
+     *          if a file of that name already exists and the {@link
      *          StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified
      *          <i>(optional specific exception)</i>
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default provider, and a security manager is
      *          installed, the {@link SecurityManager#checkRead(String) checkRead}
@@ -178,14 +178,14 @@ public abstract class SecureDirectoryStream
      * relative path then the file to delete is relative to this open directory.
      *
      * @param   path
-     *          The path of the file to delete
+     *          the path of the file to delete
      *
      * @throws  ClosedDirectoryStreamException
-     *          If the directory stream is closed
+     *          if the directory stream is closed
      * @throws  NoSuchFileException
-     *          If the the file does not exist <i>(optional specific exception)</i>
+     *          if the file does not exist <i>(optional specific exception)</i>
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default provider, and a security manager is
      *          installed, the {@link SecurityManager#checkDelete(String) checkDelete}
@@ -203,17 +203,17 @@ public abstract class SecureDirectoryStream
      * directory to delete is relative to this open directory.
      *
      * @param   path
-     *          The path of the directory to delete
+     *          the path of the directory to delete
      *
      * @throws  ClosedDirectoryStreamException
-     *          If the directory stream is closed
+     *          if the directory stream is closed
      * @throws  NoSuchFileException
-     *          If the the directory does not exist <i>(optional specific exception)</i>
+     *          if the the directory does not exist <i>(optional specific exception)</i>
      * @throws  DirectoryNotEmptyException
-     *          If the directory could not otherwise be deleted because it is
+     *          if the directory could not otherwise be deleted because it is
      *          not empty <i>(optional specific exception)</i>
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default provider, and a security manager is
      *          installed, the {@link SecurityManager#checkDelete(String) checkDelete}
@@ -238,21 +238,21 @@ public abstract class SecureDirectoryStream
      * method fails.
      *
      * @param   srcpath
-     *          The name of the file to move
+     *          the name of the file to move
      * @param   targetdir
-     *          The destination directory
+     *          the destination directory
      * @param   targetpath
-     *          The name to give the file in the destination directory
+     *          the name to give the file in the destination directory
      *
      * @throws  ClosedDirectoryStreamException
-     *          If this or the target directory stream is closed
+     *          if this or the target directory stream is closed
      * @throws  FileAlreadyExistsException
-     *          The file already exists in the target directory and cannot
+     *          if the file already exists in the target directory and cannot
      *          be replaced <i>(optional specific exception)</i>
      * @throws  AtomicMoveNotSupportedException
-     *          The file cannot be moved as an atomic file system operation
+     *          if the file cannot be moved as an atomic file system operation
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default provider, and a security manager is
      *          installed, the {@link SecurityManager#checkWrite(String) checkWrite}
@@ -279,9 +279,9 @@ public abstract class SecureDirectoryStream
      * ClosedDirectoryStreamException ClosedDirectoryStreamException}.
      *
      * @param   type
-     *          The {@code Class} object corresponding to the file attribute view
+     *          the {@code Class} object corresponding to the file attribute view
      *
-     * @return  A new file attribute view of the specified type bound to
+     * @return  a new file attribute view of the specified type bound to
      *          this directory stream, or {@code null} if the attribute view
      *          type is not available
      */
@@ -307,13 +307,13 @@ public abstract class SecureDirectoryStream
      * fail when invoked and the file does not exist.
      *
      * @param   path
-     *          The path of the file
+     *          the path of the file
      * @param   type
-     *          The {@code Class} object corresponding to the file attribute view
+     *          the {@code Class} object corresponding to the file attribute view
      * @param   options
-     *          Options indicating how symbolic links are handled
+     *          options indicating how symbolic links are handled
      *
-     * @return  A new file attribute view of the specified type bound to a
+     * @return  a new file attribute view of the specified type bound to a
      *          this directory stream, or {@code null} if the attribute view
      *          type is not available
      *

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

@@ -65,7 +65,7 @@ public class SimpleFileVisitor<T extends FileRef> implements FileVisitor<T> {
      * exception as cause.
      *
      * @throws  IOError
-     *          With the I/O exception thrown when the attempt to open the
+     *          with the I/O exception thrown when the attempt to open the
      *          directory failed
      */
     @Override
@@ -91,7 +91,7 @@ public class SimpleFileVisitor<T extends FileRef> implements FileVisitor<T> {
      * exception as cause.
      *
      * @throws  IOError
-     *          With the I/O exception thrown when the attempt to read the file
+     *          with the I/O exception thrown when the attempt to read the file
      *          attributes failed
      */
     @Override
@@ -109,7 +109,7 @@ public class SimpleFileVisitor<T extends FileRef> implements FileVisitor<T> {
      * cause.
      *
      * @throws  IOError
-     *          If iteration of the directory completed prematurely due to an
+     *          if iteration of the directory completed prematurely due to an
      *          I/O error
      */
     @Override

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

@@ -88,7 +88,7 @@ public abstract class WatchEvent<T> {
     /**
      * Returns the event kind.
      *
-     * @return  The event kind
+     * @return  the event kind
      */
     public abstract Kind<T> kind();
 
@@ -96,7 +96,7 @@ public abstract class WatchEvent<T> {
      * Returns the event count. If the event count is greater than {@code 1}
      * then this is a repeated event.
      *
-     * @return  The event count
+     * @return  the event count
      */
     public abstract int count();
 
@@ -110,7 +110,7 @@ public abstract class WatchEvent<T> {
      * the directory registered with the watch service, and the entry that is
      * created, deleted, or modified.
      *
-     * @return  The event context; may be {@code null}
+     * @return  the event context; may be {@code null}
      */
     public abstract T context();
 }

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

@@ -103,7 +103,7 @@ public abstract class WatchKey {
      *
      * <p> Note that this method does not wait if there are no events pending.
      *
-     * @return  The list of the events retrieved
+     * @return  the list of the events retrieved
      */
     public abstract List<WatchEvent<?>> pollEvents();
 
@@ -117,7 +117,7 @@ public abstract class WatchKey {
      * events then the watch key is put into the ready state and will remain in
      * that state until an event is detected or the watch key is cancelled.
      *
-     * @return  {@code true} if the watch key is valid and has been reset;
+     * @return  {@code true} if the watch key is valid and has been reset, and
      *          {@code false} if the watch key could not be reset because it is
      *          no longer {@link #isValid valid}
      */

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

@@ -126,7 +126,7 @@ public abstract class WatchService
      * has no effect.
      *
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      */
     @Override
     public abstract void close() throws IOException;
@@ -135,10 +135,10 @@ public abstract class WatchService
      * Retrieves and removes the next watch key, or {@code null} if none are
      * present.
      *
-     * @return  The next watch key, or {@code null}
+     * @return  the next watch key, or {@code null}
      *
      * @throws  ClosedWatchServiceException
-     *          If this watch service is closed
+     *          if this watch service is closed
      */
     public abstract WatchKey poll();
 
@@ -152,13 +152,13 @@ public abstract class WatchService
      *          a {@code TimeUnit} determining how to interpret the timeout
      *          parameter
      *
-     * @return  The next watch key, or {@code null}
+     * @return  the next watch key, or {@code null}
      *
      * @throws  ClosedWatchServiceException
-     *          If this watch service is closed, or it is closed while waiting
+     *          if this watch service is closed, or it is closed while waiting
      *          for the next key
      * @throws  InterruptedException
-     *          If interrupted while waiting
+     *          if interrupted while waiting
      */
     public abstract WatchKey poll(long timeout, TimeUnit unit)
         throws InterruptedException;
@@ -166,13 +166,13 @@ public abstract class WatchService
     /**
      * Retrieves and removes next watch key, waiting if none are yet present.
      *
-     * @return  The next watch key
+     * @return  the next watch key
      *
      * @throws  ClosedWatchServiceException
-     *          If this watch service is closed, or it is closed while waiting
+     *          if this watch service is closed, or it is closed while waiting
      *          for the next key
      * @throws  InterruptedException
-     *          If interrupted while waiting
+     *          if interrupted while waiting
      */
     public abstract WatchKey take() throws InterruptedException;
 }

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

@@ -64,25 +64,25 @@ public interface Watchable {
      * support.
      *
      * @param   watcher
-     *          The watch service to which this object is to be registered
+     *          the watch service to which this object is to be registered
      * @param   events
-     *          The events for which this object should be registered
+     *          the events for which this object should be registered
      * @param   modifiers
-     *          The modifiers, if any, that modify how the object is registered
+     *          the modifiers, if any, that modify how the object is registered
      *
-     * @return  A key representing the registration of this object with the
+     * @return  a key representing the registration of this object with the
      *          given watch service
      *
      * @throws  UnsupportedOperationException
-     *          If unsupported events or modifiers are specified
+     *          if unsupported events or modifiers are specified
      * @throws  IllegalArgumentException
-     *          If an invalid of combination of events are modifiers are specified
+     *          if an invalid of combination of events are modifiers are specified
      * @throws  ClosedWatchServiceException
-     *          If the watch service is closed
+     *          if the watch service is closed
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
-     *          If a security manager is installed and it denies an unspecified
+     *          if a security manager is installed and it denies an unspecified
      *          permission required to monitor this object. Implementations of
      *          this interface should specify the permission checks.
      */
@@ -102,23 +102,23 @@ public interface Watchable {
      * </pre>
      *
      * @param   watcher
-     *          The watch service to which this object is to be registered
+     *          the watch service to which this object is to be registered
      * @param   events
-     *          The events for which this object should be registered
+     *          the events for which this object should be registered
      *
-     * @return  A key representing the registration of this object with the
+     * @return  a key representing the registration of this object with the
      *          given watch service
      *
      * @throws  UnsupportedOperationException
-     *          If unsupported events are specified
+     *          if unsupported events are specified
      * @throws  IllegalArgumentException
-     *          If an invalid of combination of events are specified
+     *          if an invalid of combination of events are specified
      * @throws  ClosedWatchServiceException
-     *          If the watch service is closed
+     *          if the watch service is closed
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
-     *          If a security manager is installed and it denies an unspecified
+     *          if a security manager is installed and it denies an unspecified
      *          permission required to monitor this object. Implementations of
      *          this interface should specify the permission checks.
      */

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

@@ -118,10 +118,10 @@ public final class AclEntry {
          * The type and who components are required to have been set in order
          * to construct an {@code AclEntry}.
          *
-         * @return  A new ACL entry
+         * @return  a new ACL entry
          *
          * @throws  IllegalStateException
-         *          If the type or who component have not been set.
+         *          if the type or who component have not been set
          */
         public AclEntry build() {
             if (type == null)
@@ -134,7 +134,7 @@ public final class AclEntry {
         /**
          * Sets the type component of this builder.
          *
-         * @return  This builder
+         * @return  this builder
          */
         public Builder setType(AclEntryType type) {
             if (type == null)
@@ -146,7 +146,7 @@ public final class AclEntry {
         /**
          * Sets the principal component of this builder.
          *
-         * @return  This builder
+         * @return  this builder
          */
         public Builder setPrincipal(UserPrincipal who) {
             if (who == null)
@@ -168,10 +168,10 @@ 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.
          *
-         * @return  This builder
+         * @return  this builder
          *
          * @throws  ClassCastException
-         *          If the sets contains elements that are not of type {@code
+         *          if the set contains elements that are not of type {@code
          *          AclEntryPermission}
          */
         public Builder setPermissions(Set<AclEntryPermission> perms) {
@@ -187,7 +187,7 @@ public final class AclEntry {
          * permissions component of this builder is a copy of the permissions in
          * the given array.
          *
-         * @return  This builder
+         * @return  this builder
          */
         public Builder setPermissions(AclEntryPermission... perms) {
             Set<AclEntryPermission> set =
@@ -206,10 +206,10 @@ 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.
          *
-         * @return  This builder
+         * @return  this builder
          *
          * @throws  ClassCastException
-         *          If the sets contains elements that are not of type {@code
+         *          if the set contains elements that are not of type {@code
          *          AclEntryFlag}
          */
         public Builder setFlags(Set<AclEntryFlag> flags) {
@@ -225,7 +225,7 @@ public final class AclEntry {
          * component of this builder is a copy of the flags in the given
          * array.
          *
-         * @return  This builder
+         * @return  this builder
          */
         public Builder setFlags(AclEntryFlag... flags) {
             Set<AclEntryFlag> set = new HashSet<AclEntryFlag>(flags.length);
@@ -245,7 +245,7 @@ public final class AclEntry {
      * components is {@code null}. The initial value of the permissions and
      * flags components is the empty set.
      *
-     * @return  A new builder
+     * @return  a new builder
      */
     public static Builder newBuilder() {
         Set<AclEntryPermission> perms = Collections.emptySet();
@@ -257,9 +257,9 @@ public final class AclEntry {
      * Constructs a new builder with the components of an existing ACL entry.
      *
      * @param   entry
-     *          An ACL entry
+     *          an ACL entry
      *
-     * @return  A new builder
+     * @return  a new builder
      */
     public static Builder newBuilder(AclEntry entry) {
         return new Builder(entry.type, entry.who, entry.perms, entry.flags);
@@ -310,7 +310,7 @@ public final class AclEntry {
      * <p> This method satisfies the general contract of the {@link
      * java.lang.Object#equals(Object) Object.equals} method. </p>
      *
-     * @param   ob   The object to which this object is to be compared
+     * @param   ob   the object to which this object is to be compared
      *
      * @return  {@code true} if, and only if, the given object is an AclEntry that
      *          is identical to this AclEntry
@@ -341,7 +341,7 @@ public final class AclEntry {
      * Returns the hash-code value for this ACL entry.
      *
      * <p> This method satisfies the general contract of the {@link
-     * Object#hashCode method}.
+     * Object#hashCode} method.
      */
     @Override
     public int hashCode() {
@@ -359,7 +359,7 @@ public final class AclEntry {
     /**
      * Returns the string representation of this ACL entry.
      *
-     * @return  The string representation of this entry
+     * @return  the string representation of this entry
      */
     @Override
     public String toString() {

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

@@ -160,11 +160,11 @@ public interface AclFileAttributeView
      * existing ACL. The {@link #setAcl setAcl} method is used to update
      * the file's ACL attribute.
      *
-     * @return  An ordered list of {@link AclEntry entries} representing the
+     * @return  an ordered list of {@link AclEntry entries} representing the
      *          ACL
      *
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default provider, a security manager is
      *          installed, and it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
@@ -197,10 +197,10 @@ public interface AclFileAttributeView
      * may also cause these security related attributes to be updated.
      *
      * @param   acl
-     *          The new access control list
+     *          the new access control list
      *
      * @throws  IOException
-     *          If an I/O error occurs or the ACL is invalid
+     *          if an I/O error occurs or the ACL is invalid
      * @throws  SecurityException
      *          In the case of the default provider, a security manager is
      *          installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>

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

@@ -53,15 +53,15 @@ public interface AttributeView {
      * Reads the value of an attribute.
      *
      * @param   attribute
-     *          The attribute name (case sensitive)
+     *          the attribute name (case sensitive)
      *
-     * @return  The value of the attribute, or {@code null} if the attribute is
+     * @return  the value of the attribute, or {@code null} if the attribute is
      *          not supported
      *
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
-     *          If a security manager is set and it denies access
+     *          if a security manager is set and it denies access
      */
     Object getAttribute(String attribute) throws IOException;
 
@@ -69,24 +69,24 @@ public interface AttributeView {
      * Sets/updates the value of an attribute.
      *
      * @param   attribute
-     *          The attribute name (case sensitive)
+     *          the attribute name (case sensitive)
      * @param   value
-     *          The attribute value
+     *          the attribute value
      *
      * @throws  UnsupportedOperationException
-     *          If the attribute is not supported or this attribute view does
+     *          if the attribute is not supported or this attribute view does
      *          not support updating the value of the attribute
      * @throws  IllegalArgumentException
-     *          If the attribute value is of the correct type but has an
+     *          if the attribute value is of the correct type but has an
      *          inappropriate value
      * @throws  ClassCastException
-     *          If the attribute value is not of the expected type or is a
+     *          if the attribute value is not of the expected type or is a
      *          collection containing elements that are not of the expected
      *          type
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
-     *          If a security manager is set and it denies access
+     *          if a security manager is set and it denies access
      */
     void setAttribute(String attribute, Object value) throws IOException;
 
@@ -102,17 +102,17 @@ public interface AttributeView {
      * to other file system operations.
      *
      * @param   first
-     *          The name of an attribute to read (case sensitive)
+     *          the name of an attribute to read (case sensitive)
      * @param   rest
-     *          The names of others attributes to read (case sensitive)
+     *          the names of other attributes to read (case sensitive)
      *
-     * @return  An unmodifiable map of the attributes; may be empty. Its keys are
+     * @return  an unmodifiable map of the attributes; may be empty. Its keys are
      *          the attribute names, its values are the attribute values
      *
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
-     *          If a security manager is set and it denies access
+     *          if a security manager is set and it denies access
      */
     Map<String,?> readAttributes(String first, String... rest) throws IOException;
 }

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

@@ -125,10 +125,10 @@ public interface BasicFileAttributeView
      * <p> It is implementation specific if all file attributes are read as an
      * atomic operation with respect to other file system operations.
      *
-     * @return  The file attributes
+     * @return  the file attributes
      *
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default provider, a security manager is
      *          installed, its {@link SecurityManager#checkRead(String) checkRead}
@@ -158,22 +158,22 @@ public interface BasicFileAttributeView
      * this method has no effect.
      *
      * @param   lastModifiedTime
-     *          The new last modified time, or {@code -1L} to update it to
+     *          the new last modified time, or {@code -1L} to update it to
      *          the current time, or {@code null} to not change the attribute
      * @param   lastAccessTime
-     *          The last access time, or {@code -1L} to update it to
+     *          the last access time, or {@code -1L} to update it to
      *          the current time, or {@code null} to not change the attribute.
      * @param   createTime
-     *          The file's create time, or {@code -1L} to update it to
+     *          the file's create time, or {@code -1L} to update it to
      *          the current time, or {@code null} to not change the attribute
      * @param   unit
-     *          A {@code TimeUnit} determining how to interpret the time values
+     *          a {@code TimeUnit} determining how to interpret the time values
      *
      * @throws  IllegalArgumentException
-     *          If any of the parameters is a negative value other than {@code
+     *          if any of the parameters is a negative value other than {@code
      *          -1L}
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default provider, a security manager is
      *          installed, its  {@link SecurityManager#checkWrite(String) checkWrite}

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

@@ -53,7 +53,7 @@ public interface BasicFileAttributes {
      * <p> The {@link #resolution() resolution} method returns the {@link TimeUnit}
      * to interpret the return value of this method.
      *
-     * @return  A <code>long</code> value representing the time the file was
+     * @return  a <code>long</code> value representing the time the file was
      *          last modified since the epoch (00:00:00 GMT, January 1, 1970),
      *          or {@code -1L} if the attribute is not supported.
      */
@@ -65,7 +65,7 @@ public interface BasicFileAttributes {
      * <p> The {@link #resolution() resolution} method returns the {@link TimeUnit}
      * to interpret the return value of this method.
      *
-     * @return  A <code>long</code> value representing the time of last access
+     * @return  a <code>long</code> value representing the time of last access
      *          since the epoch (00:00:00 GMT, January 1, 1970), or {@code -1L}
      *          if the attribute is not supported.
      */
@@ -78,7 +78,7 @@ public interface BasicFileAttributes {
      * <p> The {@link #resolution() resolution} method returns the {@link TimeUnit}
      * to interpret the return value of this method.
      *
-     * @return  A <code>long</code> value representing the time the file was
+     * @return  a <code>long</code> value representing the time the file was
      *          created since the epoch (00:00:00 GMT, January 1, 1970), or
      *          {@code -1L} if the attribute is not supported.
      */
@@ -88,7 +88,7 @@ public interface BasicFileAttributes {
      * Returns the {@link TimeUnit} required to interpret the time of last
      * modification, time of last access, and creation time.
      *
-     * @return  The {@code TimeUnit} required to interpret the file time stamps
+     * @return  the {@code TimeUnit} required to interpret the file time stamps
      */
     TimeUnit resolution();
 
@@ -120,7 +120,7 @@ public interface BasicFileAttributes {
      * #isRegularFile regular} files is implementation specific and
      * therefore unspecified.
      *
-     * @return  The file size, in bytes
+     * @return  the file size, in bytes
      */
     long size();
 

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

@@ -106,10 +106,10 @@ public interface DosFileAttributeView
      * the DOS attribute in order to update this attribute.
      *
      * @param   value
-     *          The new value of the attribute
+     *          the new value of the attribute
      *
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default, and a security manager is installed,
      *          its  {@link SecurityManager#checkWrite(String) checkWrite} method
@@ -126,10 +126,10 @@ public interface DosFileAttributeView
      * the DOS attribute in order to update this attribute.
      *
      * @param   value
-     *          The new value of the attribute
+     *          the new value of the attribute
      *
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default, and a security manager is installed,
      *          its  {@link SecurityManager#checkWrite(String) checkWrite} method
@@ -146,10 +146,10 @@ public interface DosFileAttributeView
      * the DOS attribute in order to update this attribute.
      *
      * @param   value
-     *          The new value of the attribute
+     *          the new value of the attribute
      *
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default, and a security manager is installed,
      *          its  {@link SecurityManager#checkWrite(String) checkWrite} method
@@ -166,10 +166,10 @@ public interface DosFileAttributeView
      * the DOS attribute in order to update this attribute.
      *
      * @param   value
-     *          The new value of the attribute
+     *          the new value of the attribute
      *
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default, and a security manager is installed,
      *          its  {@link SecurityManager#checkWrite(String) checkWrite} method

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

@@ -49,7 +49,7 @@ public interface DosFileAttributes
      * or platform does any enforcement to prevent <em>read-only</em> files
      * from being updated is implementation specific.
      *
-     * @return  The value of the read-only attribute.
+     * @return  the value of the read-only attribute
      */
     boolean isReadOnly();
 
@@ -59,7 +59,7 @@ public interface DosFileAttributes
      * <p> This attribute is often used to indicate if the file is visible to
      * users.
      *
-     * @return  The value of the hidden attribute.
+     * @return  the value of the hidden attribute
      */
     boolean isHidden();
 
@@ -68,7 +68,7 @@ public interface DosFileAttributes
      *
      * <p> This attribute is typically used by backup programs.
      *
-     * @return  The value of the archive attribute.
+     * @return  the value of the archive attribute
      */
     boolean isArchive();
 
@@ -78,7 +78,7 @@ public interface DosFileAttributes
      * <p> This attribute is often used to indicate that the file is a component
      * of the operating system.
      *
-     * @return  The value of the system attribute.
+     * @return  the value of the system attribute
      */
     boolean isSystem();
 }

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

@@ -65,7 +65,7 @@ public interface FileOwnerAttributeView
      * @return  the file owner
      *
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default provider, a security manager is
      *          installed, and it denies {@link
@@ -84,10 +84,10 @@ public interface FileOwnerAttributeView
      * to set the file owner to a user principal that is not a group.
      *
      * @param   owner
-     *          The new file owner
+     *          the new file owner
      *
      * @throws  IOException
-     *          If an I/O error occurs, or the {@code owner} parameter is a
+     *          if an I/O error occurs, or the {@code owner} parameter is a
      *          group and this implementation does not support setting the owner
      *          to a group
      * @throws  SecurityException

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

@@ -163,13 +163,13 @@ public interface PosixFileAttributeView
      * Updates the file permissions.
      *
      * @param   perms
-     *          The new set of permissions
+     *          the new set of permissions
      *
      * @throws  ClassCastException
-     *          If the sets contains elements that are not of type {@code
+     *          if the sets contains elements that are not of type {@code
      *          PosixFilePermission}
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default provider, a security manager is
      *          installed, and it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
@@ -182,10 +182,10 @@ public interface PosixFileAttributeView
      * Updates the file group-owner.
      *
      * @param   group
-     *          The new file group-owner
-
+     *          the new file group-owner
+     *
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default provider, and a security manager is
      *          installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>

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

@@ -47,7 +47,7 @@ public interface PosixFileAttributes
     /**
      * Returns the owner of the file.
      *
-     * @return  The file owner
+     * @return  the file owner
      *
      * @see PosixFileAttributeView#setOwner
      */
@@ -56,7 +56,7 @@ public interface PosixFileAttributes
     /**
      * Returns the group owner of the file.
      *
-     * @return  The file group owner
+     * @return  the file group owner
      *
      * @see PosixFileAttributeView#setGroup
      */
@@ -69,7 +69,7 @@ public interface PosixFileAttributes
      * to be modified and passed to the {@link PosixFileAttributeView#setPermissions
      * setPermissions} method to update the file's permissions.
      *
-     * @return  The file permissions
+     * @return  the file permissions
      *
      * @see PosixFileAttributeView#setPermissions
      */

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

@@ -64,9 +64,9 @@ public class PosixFilePermissions {
      * {@code PosixFilePermission} then these elements are ignored.
      *
      * @param   perms
-     *          The set of permissions
+     *          the set of permissions
      *
-     * @return  The string representation of the permission set
+     * @return  the string representation of the permission set
      *
      * @see #fromString
      */
@@ -114,12 +114,12 @@ public class PosixFilePermissions {
      * </pre>
      *
      * @param   perms
-     *          String representing a set of permissions
+     *          string representing a set of permissions
      *
-     * @return  The resulting set of permissions
+     * @return  the resulting set of permissions
      *
      * @throws  IllegalArgumentException
-     *          If the string cannot be converted to a set of permissions
+     *          if the string cannot be converted to a set of permissions
      *
      * @see #toString(Set)
      */
@@ -146,13 +146,13 @@ public class PosixFilePermissions {
      * methods.
      *
      * @param   perms
-     *          The set of permissions
+     *          the set of permissions
      *
-     * @return  An attribute encapsulating the given file permissions with
+     * @return  an attribute encapsulating the given file permissions with
      *          {@link FileAttribute#name name} {@code "posix:permissions"}
      *
      * @throws  ClassCastException
-     *          If the sets contains elements that are not of type {@code
+     *          if the set contains elements that are not of type {@code
      *          PosixFilePermission}
      */
     public static FileAttribute<Set<PosixFilePermission>>

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

@@ -62,14 +62,14 @@ public abstract class UserPrincipalLookupService {
      * Lookup a user principal by name.
      *
      * @param   name
-     *          The string representation of the user principal to lookup
+     *          the string representation of the user principal to lookup
      *
-     * @return  A user principal
+     * @return  a user principal
      *
      * @throws  UserPrincipalNotFoundException
-     *          The principal does not exist
+     *          the principal does not exist
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default provider, and a security manager is
      *          installed, it checks {@link RuntimePermission}<tt>("lookupUserInformation")</tt>
@@ -87,14 +87,14 @@ public abstract class UserPrincipalLookupService {
      * lookupPrincipalByName}.
      *
      * @param   group
-     *          The string representation of the group to lookup
+     *          the string representation of the group to lookup
      *
-     * @return  A user principal.
+     * @return  a user principal
      *
      * @throws  UserPrincipalNotFoundException
-     *          The principal does not exist or is not a group
+     *          the principal does not exist or is not a group
      * @throws  IOException
-     *          If an I/O error occurs
+     *          if an I/O error occurs
      * @throws  SecurityException
      *          In the case of the default provider, and a security manager is
      *          installed, it checks {@link RuntimePermission}<tt>("lookupUserInformation")</tt>

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

@@ -45,7 +45,7 @@ public class UserPrincipalNotFoundException
      * Constructs an instance of this class.
      *
      * @param   name
-     *          The principal name; may be {@code null}
+     *          the principal name; may be {@code null}
      */
     public UserPrincipalNotFoundException(String name) {
         super();
@@ -56,7 +56,7 @@ public class UserPrincipalNotFoundException
      * Returns the user principal name if this exception was created with the
      * user principal name that was not found, otherwise <tt>null</tt>.
      *
-     * @return  The user principal name or {@code null}
+     * @return  the user principal name or {@code null}
      */
     public String getName() {
         return name;

src/share/classes/java/nio/file/package-info.java

@@ -24,7 +24,7 @@
  */
 
 /**
- * Define interfaces and classes for the Java virtual machine to access files,
+ * Defines interfaces and classes for the Java virtual machine to access files,
  * file attributes, and file systems.
  *
  * <p> The java.nio.file package defines classes to access files and file