Correct more style issues and remove warnings

This change is a follow-up to post-merge comments in googleapis#706 made by
@ajkannan and @aozarov. The following changes have been made:

- Don't use @nullable on equals() methods
- Don't `throws Exception` in test methods unless needed
- Use incomplete sentences in JavaDoc summary fragment
- Capitalize Cloud Storage
- Get rid of some one-line JavaDocs
- Use @code formatting when appropriate
- Remove Paths.get() usages which is deprecated in Java 8
- Remove @SuppressWarnings("null") which no one uses

Author: jart

gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/gcloud/storage/contrib/nio/CloudStorageConfiguration.java

@@ -7,13 +7,13 @@
 import java.util.Map;
 
 /**
- * Configuration for a {@link CloudStorageFileSystem} instance.
+ * Configuration for {@link CloudStorageFileSystem} instances.
  */
 @AutoValue
 public abstract class CloudStorageConfiguration {
 
   /**
-   * Returns path of the current working directory. This defaults to the root directory.
+   * Returns path of current working directory. This defaults to the root directory.
    */
   public abstract String workingDirectory();
 
@@ -31,10 +31,14 @@ public abstract class CloudStorageConfiguration {
    */
   public abstract boolean stripPrefixSlash();
 
-  /** Return {@code true} if paths with a trailing slash should be treated as fake directories. */
+  /**
+   * Returns {@code true} if paths with a trailing slash should be treated as fake directories.
+   */
   public abstract boolean usePseudoDirectories();
 
-  /** Returns the block size (in bytes) used when talking to the GCS HTTP server. */
+  /**
+   * Returns block size (in bytes) used when talking to the GCS HTTP server.
+   */
   public abstract int blockSize();
 
   /**
@@ -50,7 +54,8 @@ public static Builder builder() {
     return new Builder();
   }
 
-  /** Builder for {@link CloudStorageConfiguration}.
+  /**
+   * Builder for {@link CloudStorageConfiguration}.
    */
   public static final class Builder {
 
@@ -61,8 +66,8 @@ public static final class Builder {
     private int blockSize = CloudStorageFileSystem.BLOCK_SIZE_DEFAULT;
 
     /**
-     * Changes the current working directory for a new filesystem. This cannot be changed once it's
-     * been set. You'll need to simply create another filesystem object.
+     * Changes current working directory for new filesystem. This cannot be changed once it's
+     * been set. You'll need to create another {@link CloudStorageFileSystem} object.
      *
      * @throws IllegalArgumentException if {@code path} is not absolute.
      */
@@ -92,7 +97,8 @@ public Builder stripPrefixSlash(boolean value) {
       return this;
     }
 
-    /** Configures if paths with a trailing slash should be treated as fake directories.
+    /**
+     * Configures if paths with a trailing slash should be treated as fake directories.
      */
     public Builder usePseudoDirectories(boolean value) {
       usePseudoDirectories = value;
@@ -109,7 +115,8 @@ public Builder blockSize(int value) {
       return this;
     }
 
-    /** Creates a new instance, but does not destroy the builder.
+    /**
+     * Creates new instance without destroying builder.
      */
     public CloudStorageConfiguration build() {
       return new AutoValue_CloudStorageConfiguration(

gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/gcloud/storage/contrib/nio/CloudStorageFileAttributeView.java

@@ -12,7 +12,6 @@
 import java.nio.file.attribute.FileTime;
 import java.util.Objects;
 
-import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
 
 /**
@@ -59,7 +58,7 @@ public void setTimes(FileTime lastModifiedTime, FileTime lastAccessTime, FileTim
   }
 
   @Override
-  public boolean equals(@Nullable Object other) {
+  public boolean equals(Object other) {
     return this == other
         || other instanceof CloudStorageFileAttributeView
             && Objects.equals(storage, ((CloudStorageFileAttributeView) other).storage)

gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/gcloud/storage/contrib/nio/CloudStorageFileAttributes.java

@@ -7,53 +7,55 @@
 import java.nio.file.attribute.BasicFileAttributes;
 import java.util.List;
 
-/** Interface for attributes on a cloud storage file or pseudo-directory. */
+/**
+ * Interface for attributes on a Cloud Storage file or pseudo-directory.
+ */
 public interface CloudStorageFileAttributes extends BasicFileAttributes {
 
   /**
-   * Returns the HTTP etag hash for this object.
+   * Returns HTTP etag hash of object contents.
    *
    * @see "https://developers.google.com/storage/docs/hashes-etags"
    */
   Optional<String> etag();
 
   /**
-   * Returns the mime type (e.g. text/plain) if it was set for this object.
+   * Returns mime type (e.g. text/plain), if set.
    *
    * @see "http://en.wikipedia.org/wiki/Internet_media_type#List_of_common_media_types"
    */
   Optional<String> mimeType();
 
   /**
-   * Returns the ACL value on this Cloud Storage object.
+   * Returns access control list.
    *
    * @see "https://developers.google.com/storage/docs/reference-headers#acl"
    */
   Optional<List<Acl>> acl();
 
   /**
-   * Returns the {@code Cache-Control} HTTP header value, if set on this object.
+   * Returns {@code Cache-Control} HTTP header value, if set.
    *
    * @see "https://developers.google.com/storage/docs/reference-headers#cachecontrol"
    */
   Optional<String> cacheControl();
 
   /**
-   * Returns the {@code Content-Encoding} HTTP header value, if set on this object.
+   * Returns {@code Content-Encoding} HTTP header value, if set.
    *
    * @see "https://developers.google.com/storage/docs/reference-headers#contentencoding"
    */
   Optional<String> contentEncoding();
 
   /**
-   * Returns the {@code Content-Disposition} HTTP header value, if set on this object.
+   * Returns {@code Content-Disposition} HTTP header value, if set.
    *
    * @see "https://developers.google.com/storage/docs/reference-headers#contentdisposition"
    */
   Optional<String> contentDisposition();
 
   /**
-   * Returns user-specified metadata associated with this object.
+   * Returns user-specified metadata.
    *
    * @see "https://developers.google.com/storage/docs/reference-headers#contentdisposition"
    */

gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/gcloud/storage/contrib/nio/CloudStorageFileSystem.java

@@ -18,11 +18,10 @@
 import java.util.Objects;
 import java.util.Set;
 
-import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
 
 /**
- * Google Cloud Storage {@link FileSystem}
+ * Google Cloud Storage {@link FileSystem} implementation.
  *
  * @see <a href="https://developers.google.com/storage/docs/concepts-techniques#concepts">
  *        Concepts and Terminology</a>
@@ -33,7 +32,7 @@
 public final class CloudStorageFileSystem extends FileSystem {
 
   /**
-   * Returns Google Cloud Storage {@link FileSystem} object for a given bucket name.
+   * Returns Google Cloud Storage {@link FileSystem} object for {@code bucket}.
    *
    * <p><b>NOTE:</b> You may prefer to use Java's standard API instead:<pre>   {@code
    *
@@ -52,7 +51,7 @@ public static CloudStorageFileSystem forBucket(String bucket) {
   }
 
   /**
-   * Creates a new filesystem for a particular bucket, with customizable settings.
+   * Creates new file system instance for {@code bucket}, with customizable settings.
    *
    * @see #forBucket(String)
    */
@@ -88,21 +87,21 @@ public CloudStorageFileSystemProvider provider() {
   }
 
   /**
-   * Returns the Cloud Storage bucket name being served by this file system.
+   * Returns Cloud Storage bucket name being served by this file system.
    */
   public String bucket() {
     return bucket;
   }
 
   /**
-   * Returns the configuration object for this filesystem instance.
+   * Returns configuration object for this file system instance.
    */
   public CloudStorageConfiguration config() {
     return config;
   }
 
   /**
-   * Converts a cloud storage object name to a {@link Path} object.
+   * Converts Cloud Storage object name to a {@link Path} object.
    */
   @Override
   public CloudStoragePath getPath(String first, String... more) {
@@ -186,7 +185,7 @@ public WatchService newWatchService() throws IOException {
   }
 
   @Override
-  public boolean equals(@Nullable Object other) {
+  public boolean equals(Object other) {
     return this == other
         || other instanceof CloudStorageFileSystem
             && Objects.equals(config, ((CloudStorageFileSystem) other).config)

gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/gcloud/storage/contrib/nio/CloudStorageFileSystemProvider.java

@@ -57,7 +57,7 @@
 import javax.annotation.concurrent.ThreadSafe;
 
 /**
- * Google Cloud Storage {@link FileSystemProvider}.
+ * Google Cloud Storage {@link FileSystemProvider} implementation.
  */
 @ThreadSafe
 @AutoService(FileSystemProvider.class)
@@ -100,15 +100,15 @@ public String getScheme() {
   }
 
   /**
-   * Returns cloud storage file system, provided a URI with no path, e.g. {@code gs://bucket}.
+   * Returns Cloud Storage file system, provided a URI with no path, e.g. {@code gs://bucket}.
    */
   @Override
   public CloudStorageFileSystem getFileSystem(URI uri) {
     return newFileSystem(uri, Collections.<String, Object>emptyMap());
   }
 
   /**
-   * Returns cloud storage file system, provided a URI with no path, e.g. {@code gs://bucket}.
+   * Returns Cloud Storage file system, provided a URI with no path, e.g. {@code gs://bucket}.
    */
   @Override
   public CloudStorageFileSystem newFileSystem(URI uri, Map<String, ?> env) {
@@ -537,7 +537,7 @@ public FileStore getFileStore(Path path) {
   }
 
   @Override
-  public boolean equals(@Nullable Object other) {
+  public boolean equals(Object other) {
     return this == other
         || other instanceof CloudStorageFileSystemProvider
             && Objects.equals(storage, ((CloudStorageFileSystemProvider) other).storage);

gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/gcloud/storage/contrib/nio/CloudStorageObjectAttributes.java

@@ -14,11 +14,10 @@
 import java.util.Objects;
 
 import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
 
 /**
- * Metadata for a Google Cloud Storage object.
+ * Metadata for a Google Cloud Storage file.
  */
 @Immutable
 final class CloudStorageObjectAttributes implements CloudStorageFileAttributes {
@@ -47,67 +46,36 @@ public FileTime lastModifiedTime() {
     return creationTime();
   }
 
-  /**
-   * Returns the HTTP etag hash for this object.
-   */
   @Override
   public Optional<String> etag() {
     return Optional.fromNullable(info.etag());
   }
 
-  /**
-   * Returns the mime type (e.g. text/plain) if it was set for this object.
-   */
   @Override
   public Optional<String> mimeType() {
     return Optional.fromNullable(info.contentType());
   }
 
-  /**
-   * Returns the ACL value on this Cloud Storage object.
-   *
-   * @see "https://developers.google.com/storage/docs/reference-headers#acl"
-   */
   @Override
   public Optional<List<Acl>> acl() {
     return Optional.fromNullable(info.acl());
   }
 
-  /**
-   * Returns the {@code Cache-Control} HTTP header value, if set on this object.
-   *
-   * @see "https://developers.google.com/storage/docs/reference-headers#cachecontrol"
-   */
   @Override
   public Optional<String> cacheControl() {
     return Optional.fromNullable(info.cacheControl());
   }
 
-  /**
-   * Returns the {@code Content-Encoding} HTTP header value, if set on this object.
-   *
-   * @see "https://developers.google.com/storage/docs/reference-headers#contentencoding"
-   */
   @Override
   public Optional<String> contentEncoding() {
     return Optional.fromNullable(info.contentEncoding());
   }
 
-  /**
-   * Returns the {@code Content-Disposition} HTTP header value, if set on this object.
-   *
-   * @see "https://developers.google.com/storage/docs/reference-headers#contentdisposition"
-   */
   @Override
   public Optional<String> contentDisposition() {
     return Optional.fromNullable(info.contentDisposition());
   }
 
-  /**
-   * Returns user-specified metadata associated with this object.
-   *
-   * @see "https://developers.google.com/storage/docs/reference-headers#contentdisposition"
-   */
   @Override
   public ImmutableMap<String, String> userMetadata() {
     if (null == info.metadata()) {
@@ -147,7 +115,7 @@ public Object fileKey() {
   }
 
   @Override
-  public boolean equals(@Nullable Object other) {
+  public boolean equals(Object other) {
     return this == other
         || other instanceof CloudStorageObjectAttributes
             && Objects.equals(info, ((CloudStorageObjectAttributes) other).info);

gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/gcloud/storage/contrib/nio/CloudStorageObjectImmutableException.java

@@ -1,7 +1,7 @@
 package com.google.gcloud.storage.contrib.nio;
 
 /**
- * Exception thrown to indicate we don't support a mutation of a cloud storage object.
+ * Exception reminding user that Cloud Storage objects can't be mutated.
  */
 public final class CloudStorageObjectImmutableException extends UnsupportedOperationException {
 

gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/gcloud/storage/contrib/nio/CloudStoragePath.java

@@ -274,7 +274,7 @@ public int compareTo(Path other) {
   }
 
   @Override
-  public boolean equals(@Nullable Object other) {
+  public boolean equals(Object other) {
     return this == other
         || other instanceof CloudStoragePath
             && Objects.equals(bucket(), ((CloudStoragePath) other).bucket())

gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/gcloud/storage/contrib/nio/CloudStoragePseudoDirectoryAttributes.java

@@ -10,7 +10,7 @@
 import java.util.List;
 
 /**
- * Metadata for a cloud storage pseudo-directory.
+ * Metadata for a Cloud Storage pseudo-directory.
  */
 final class CloudStoragePseudoDirectoryAttributes implements CloudStorageFileAttributes {
 

gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/gcloud/storage/contrib/nio/CloudStorageUtil.java

@@ -30,7 +30,7 @@ static CloudStoragePath checkPath(Path path) {
     if (!(checkNotNull(path) instanceof CloudStoragePath)) {
       throw new ProviderMismatchException(
           String.format(
-              "Not a cloud storage path: %s (%s)", path, path.getClass().getSimpleName()));
+              "Not a Cloud Storage path: %s (%s)", path, path.getClass().getSimpleName()));
     }
     return (CloudStoragePath) path;
   }