Minor javadoc fixes to gcloud-java-nio

mziccard · mziccard · commit 0bef38d53d04 · 2016-06-30T11:35:02.000+02:00
diff --git a/gcloud-java-contrib/README.md b/gcloud-java-contrib/README.md
@@ -13,7 +13,7 @@ Contents
 --------
 
  * [gcloud-java-nio](./gcloud-java-nio/): NIO Filesystem Provider for Google Cloud Storage.
- * [gcloud-java-nio-examples](./gcloud-java-nio-examples/): How to add GCS NIO after the fact.
+ * [gcloud-java-nio-examples](./gcloud-java-nio-examples/): How to add Google Cloud Storage NIO after the fact.
 
 Quickstart
 ----------
diff --git a/gcloud-java-contrib/gcloud-java-nio-examples/README.md b/gcloud-java-contrib/gcloud-java-nio-examples/README.md
@@ -1,8 +1,8 @@
 Example of adding the Google Cloud Storage NIO Provider to a legacy jar
 =======================================================================
 
-This project shows how to add GCS capabilities to a jar file for a Java 7 application
-that uses Java NIO without the need to recompile.
+This project shows how to add Google Cloud Storage capabilities to a jar file for a Java 7
+application that uses Java NIO without the need to recompile.
 
 Note that whenever possible, you instead want to recompile the app and use the normal
 dependency mechanism to add a dependency to gcloud-java-nio. You can see examples of
@@ -25,19 +25,20 @@ To run this example:
     java -cp gcloud-java-contrib/gcloud-java-nio/target/gcloud-java-nio-0.2.5-SNAPSHOT-shaded.jar:gcloud-java-contrib/gcloud-java-nio-examples/target/gcloud-java-nio-examples-0.2.5-SNAPSHOT.jar com.google.cloud.nio.examples.ListFilesystems
     ```
 
-    Notice that it lists gcs, which it wouldn't if you ran it without the nio jar:
+    Notice that it lists Google Cloud Storage, which it wouldn't if you ran it without the NIO jar:
     ```
     java -cp gcloud-java-contrib/gcloud-java-nio-examples/target/gcloud-java-nio-examples-0.2.5-SNAPSHOT.jar com.google.cloud.nio.examples.ListFilesystems
     ```
 
-The sample doesn't have anything about GCS in it. It gets that ability from the nio jar that
-we're adding to the classpath. You can use the nio "fat shaded" jar for this purpose as it also
-includes the dependencies for gcloud-java-nio.
+The sample doesn't have anything about Google Cloud Storage in it. It gets that ability from the NIO
+jar that we're adding to the classpath. You can use the NIO "fat shaded" jar for this purpose as it
+also includes the dependencies for gcloud-java-nio.
 The underlying mechanism is Java's standard [ServiceLoader](https://docs.oracle.com/javase/7/docs/api/java/util/ServiceLoader.html)
 facility, the [standard way](http://docs.oracle.com/javase/7/docs/technotes/guides/io/fsp/filesystemprovider.html) to plug in NIO providers like this one.
 
 If you have access to a project's source code you can also simply add gcloud-java-nio as
-a dependency and let Maven pull in the required dependencies (this is what the nio unit tests do).
-This approach is preferable as the fat jar approach may waste memory on multiple copies of dependencies.
+a dependency and let Maven pull in the required dependencies (this is what the NIO unit tests do).
+This approach is preferable as the fat jar approach may waste memory on multiple copies of
+dependencies.
 
-[developers-console]:https://console.developers.google.com/
+[developers-console]:https://console.developers.google.com/
diff --git a/gcloud-java-contrib/gcloud-java-nio-examples/pom.xml b/gcloud-java-contrib/gcloud-java-nio-examples/pom.xml
@@ -6,7 +6,7 @@
   <name>GCloud Java NIO examples</name>
   <url>https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-contrib/gcloud-java-nio-examples</url>
   <description>
-    Demonstrates how to use the gcloud-java-nio jar to add GCS functionality to legacy code.
+    Demonstrates how to use the gcloud-java-nio jar to add Google Cloud Storage functionality to legacy code.
   </description>
   <parent>
     <groupId>com.google.cloud</groupId>
diff --git a/gcloud-java-contrib/gcloud-java-nio/README.md b/gcloud-java-contrib/gcloud-java-nio/README.md
@@ -141,7 +141,7 @@ yet implemented:
  * Resuming upload or download
  * Generations
  * File attributes
- * (more)
+ * (more - list is not exhaustive)
 
 Some features are not on the roadmap: this library would be a poor choice to
 mirror a local filesystem onto the cloud because Google Cloud Storage has a
diff --git a/gcloud-java-contrib/gcloud-java-nio/pom.xml b/gcloud-java-contrib/gcloud-java-nio/pom.xml
@@ -6,7 +6,7 @@
   <name>GCloud Java NIO</name>
   <url>https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-contrib/gcloud-java-nio</url>
   <description>
-    FileSystemProvider for Java NIO to access GCS transparently.
+    FileSystemProvider for Java NIO to access Google Cloud Storage transparently.
   </description>
   <parent>
     <groupId>com.google.cloud</groupId>
diff --git a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageConfiguration.java b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageConfiguration.java
@@ -55,7 +55,7 @@ public abstract class CloudStorageConfiguration {
   public abstract boolean usePseudoDirectories();
 
   /**
-   * Returns block size (in bytes) used when talking to the GCS HTTP server.
+   * Returns block size (in bytes) used when talking to the Google Cloud Storage HTTP server.
    */
   public abstract int blockSize();
 
diff --git a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageFileSystem.java b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageFileSystem.java
@@ -97,9 +97,10 @@ public static CloudStorageFileSystem forBucket(String bucket, CloudStorageConfig
   /**
    * Returns Google Cloud Storage {@link FileSystem} object for {@code bucket}.
    *
-   * <p>GCS file system objects are basically free. You can create as many as you want, even if you
-   * have multiple instances for the same bucket. There's no actual system resources associated
-   * with this object. Therefore calling {@link #close()} on the returned value is optional.
+   * <p>Google Cloud Storage file system objects are basically free. You can create as many as you
+   * want, even if you have multiple instances for the same bucket. There's no actual system
+   * resources associated with this object. Therefore calling {@link #close()} on the returned value
+   * is optional.
    *
    * <p><b>Note:</b> It is also possible to instantiate this class via Java's
    * {@code FileSystems.getFileSystem(URI.create("gs://bucket"))}. We discourage you
@@ -151,7 +152,7 @@ public CloudStorageConfiguration config() {
   public CloudStoragePath getPath(String first, String... more) {
     checkArgument(
         !first.startsWith(URI_SCHEME + ":"),
-        "GCS FileSystem.getPath() must not have schema and bucket name: %s",
+        "Google Cloud Storage FileSystem.getPath() must not have schema and bucket name: %s",
         first);
     return CloudStoragePath.getPath(this, first, more);
   }
@@ -196,7 +197,8 @@ public Iterable<Path> getRootDirectories() {
   }
 
   /**
-   * Returns nothing because GCS doesn't have disk partitions of limited size, or anything similar.
+   * Returns nothing because Google Cloud Storage doesn't have disk partitions of limited size, or
+   * anything similar.
    */
   @Override
   public Iterable<FileStore> getFileStores() {
diff --git a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageFileSystemProvider.java b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageFileSystemProvider.java
@@ -77,7 +77,8 @@
  *
  * <p><b>Note:</b> This class should never be used directly. This class is instantiated by the
  * service loader and called through a standardized API, e.g. {@link java.nio.file.Files}. However
- * the javadocs in this class serve as useful documentation for the behavior of the GCS NIO library.
+ * the javadocs in this class serve as useful documentation for the behavior of the Google Cloud
+ * Storage NIO library.
  */
 @Singleton
 @ThreadSafe
@@ -481,7 +482,7 @@ public boolean isSameFile(Path path, Path path2) {
   }
 
   /**
-   * Always returns {@code false}, because GCS doesn't support hidden files.
+   * Always returns {@code false}, because Google Cloud Storage doesn't support hidden files.
    */
   @Override
   public boolean isHidden(Path path) {
@@ -561,7 +562,7 @@ public <V extends FileAttributeView> V getFileAttributeView(
   }
 
   /**
-   * Does nothing since GCS uses fake directories.
+   * Does nothing since Google Cloud Storage uses fake directories.
    */
   @Override
   public void createDirectory(Path dir, FileAttribute<?>... attrs) {
diff --git a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageOption.java b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageOption.java
@@ -25,17 +25,17 @@
 public interface CloudStorageOption {
 
   /**
-   * Interface for GCS options that can be specified when opening files.
+   * Interface for Google Cloud Storage options that can be specified when opening files.
    */
   interface Open extends CloudStorageOption, OpenOption {}
 
   /**
-   * Interface for GCS options that can be specified when copying files.
+   * Interface for Google Cloud Storage options that can be specified when copying files.
    */
   interface Copy extends CloudStorageOption, CopyOption {}
 
   /**
-   * Interface for GCS options that can be specified when opening or copying files.
+   * Interface for Google Cloud Storage options that can be specified when opening or copying files.
    */
   interface OpenCopy extends Open, Copy {}
 }
diff --git a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageOptions.java b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageOptions.java
@@ -83,7 +83,7 @@ public static CloudStorageOption.OpenCopy withUserMetadata(String key, String va
   }
 
   /**
-   * Sets the block size (in bytes) when talking to the GCS server.
+   * Sets the block size (in bytes) when talking to the Google Cloud Storage server.
    *
    * <p>The default is {@value CloudStorageFileSystem#BLOCK_SIZE_DEFAULT}.
    */
diff --git a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStoragePath.java b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStoragePath.java
@@ -139,7 +139,8 @@ private UnixPath toRealPathInternal(boolean errorCheck) {
       objectName = objectName.removeBeginningSeparator();
     }
     checkArgument(
-        !errorCheck || !objectName.isEmpty(), "I/O not allowed on empty GCS object names.");
+        !errorCheck || !objectName.isEmpty(),
+        "I/O not allowed on empty Google Cloud Storage object names.");
     return objectName;
   }
 
@@ -256,8 +257,8 @@ public WatchKey register(WatchService watcher, Kind<?>... events) {
   }
 
   /**
-   * Throws {@link UnsupportedOperationException} because GCS files are not backed by the local file
-   * system.
+   * Throws {@link UnsupportedOperationException} because Google Cloud Storage files are not backed
+   * by the local file system.
    */
   @Override
   public File toFile() {
diff --git a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageUtil.java b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageUtil.java
@@ -36,9 +36,9 @@ static void checkBucket(String bucket) {
         "Invalid bucket name: '"
             + bucket
             + "'. "
-            + "GCS bucket names must contain only lowercase letters, numbers, dashes (-), "
-            + "underscores (_), and dots (.). Bucket names must start and end with a number or a "
-            + "letter. See the following page for more details: "
+            + "Google Cloud Storage bucket names must contain only lowercase letters, numbers, "
+            + "dashes (-), underscores (_), and dots (.). Bucket names must start and end with a "
+            + "number or a letter. See the following page for more details: "
             + "https://developers.google.com/storage/docs/bucketnaming");
   }
 
diff --git a/gcloud-java-contrib/gcloud-java-nio/src/test/java/com/google/cloud/storage/contrib/nio/it/ITGcsNio.java b/gcloud-java-contrib/gcloud-java-nio/src/test/java/com/google/cloud/storage/contrib/nio/it/ITGcsNio.java
@@ -58,21 +58,20 @@
 import java.util.logging.Logger;
 
 /**
- * Integration test for gcloud-nio.
+ * Integration test for gcloud-java-nio.
  *
- * <p>This test actually talks to GCS (you need an account) and tests both reading and writing. You
- * *must* set the {@code GOOGLE_APPLICATION_CREDENTIALS} environment variable for this test to work.
- * It must contain the name of a local file that contains your Service Account JSON Key.
+ * <p>This test actually talks to Google Cloud Storage (you need an account) and tests both reading
+ * and writing. You *must* set the {@code GOOGLE_APPLICATION_CREDENTIALS} environment variable for
+ * this test to work. It must contain the name of a local file that contains your Service Account
+ * JSON Key.
  *
- * <p>The instructions for how to get the Service Account JSON Key are
- * at https://cloud.google.com/storage/docs/authentication?hl=en#service_accounts
+ * <p>See <a href="https://cloud.google.com/storage/docs/authentication?hl=en#service_accounts">
+ * Service Accounts</a> for instructions on how to get the Service Account JSON Key.
  *
- * <p>The short version is this: go to cloud.google.com/console,
- * select your project, search for "API manager", click "Credentials",
- * click "create credentials/service account key", new service account,
- * JSON. The contents of the file that's sent to your browsers is your
+ * <p>The short version is this: go to cloud.google.com/console, select your project, search for
+ * "API manager", click "Credentials", click "create credentials/service account key", new service
+ * account, JSON. The contents of the file that's sent to your browsers is your
  * "Service Account JSON Key".
- *
  */
 @RunWith(JUnit4.class)
 public class ITGcsNio {
diff --git a/gcloud-java-examples/README.md b/gcloud-java-examples/README.md
@@ -46,9 +46,9 @@ To run examples from your command line:
 
     Before running the example, go to the [Google Developers Console][developers-console] to ensure
     that BigQuery API is enabled. You can upload a CSV file `my_csv_file` to the `my_bucket` bucket
-    (replace `my_csv_file` and `my_bucket` with actual file and bucket names) using the GCS
-    [web browser](https://console.developers.google.com/storage/browser). The CSV file will be used to
-    load data into a BigQuery table and should look something like:
+    (replace `my_csv_file` and `my_bucket` with actual file and bucket names) using the Google Cloud
+    Storage [web browser](https://console.developers.google.com/storage/browser). The CSV file will
+    be used to load data into a BigQuery table and should look something like:
     ```csv
     value1
     value2
@@ -143,8 +143,9 @@ To run examples from your command line:
     target/appassembler/bin/Stat gs://mybucket/myfile.txt
     ```
 
-    The sample doesn't have anything special about GCS in it, it just opens files via the NIO API.
-    It lists gcloud-java-nio as a dependency, and that enables it to interpret `gs://` paths.
+    The sample doesn't have anything special about Google Cloud Storage in it, it just opens files
+    via the NIO API. It lists gcloud-java-nio as a dependency, and that enables it to interpret
+    `gs://` paths.
 
 Troubleshooting
 ---------------
diff --git a/gcloud-java-examples/src/main/java/com/google/cloud/examples/nio/Stat.java b/gcloud-java-examples/src/main/java/com/google/cloud/examples/nio/Stat.java
@@ -31,9 +31,9 @@
  *
  * <p>It's meant to be used to test GCloud's integration with Java NIO.
  *
- * <p>You can either use the '--check' argument to see whether GCS is enabled,
- * or you can directly pass in a GCS file name to use. In that case you have to
- * be logged in (using e.g. the gcloud auth command).
+ * <p>You can either use the '--check' argument to see whether Google Cloud Storage is enabled, or
+ * you can directly pass in a Google Cloud Storage file name to use. In that case you have to be
+ * logged in (using e.g. the gcloud auth command).
  *
  * <p>See the
  * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/README.md">
@@ -92,13 +92,13 @@ private static void help() {
          "   to list the filesystem providers.",
          "",
          " * --check",
-         "   to double-check the GCS provider is installed.",
+         "   to double-check the Google Cloud Storage provider is installed.",
          "",
          "The purpose of this tool is to demonstrate that the gcloud NIO filesystem provider",
          "can add Google Cloud Storage support to programs not explicitly designed for it.",
          "",
          "This tool normally knows nothing of Google Cloud Storage. If you pass it --check",
-         "or a GCS file name (e.g. gs://mybucket/myfile), it will show an error.",
+         "or a Google Cloud Storage file name (e.g. gs://mybucket/myfile), it will show an error.",
          "However, by just adding the gcloud-nio jar as a dependency and recompiling, this tool is",
          "made aware of gs:// paths and can access files on the cloud.",
          "",
diff --git a/gcloud-java-storage/src/main/java/com/google/cloud/storage/testing/package-info.java b/gcloud-java-storage/src/main/java/com/google/cloud/storage/testing/package-info.java
@@ -15,9 +15,7 @@
  */
 
 /**
- * Two testing helpers for Google Cloud Storage.
- *
- * RemoteGcsHelper helps with testing on the actual cloud.
+ * A testing helper for Google Cloud Storage.
  *
  * <p>A simple usage example:
  *
@@ -29,26 +27,6 @@
  * storage.create(BucketInfo.of(bucket));
  * } </pre>
  *
- * <p>After the test:
- * <pre> {@code
- * RemoteStorageHelper.forceDelete(storage, bucket, 5, TimeUnit.SECONDS);
- * } </pre>
- *
- * LocalGcsHelper helps with testing on an in-memory filesystem (this is best for unit tests).
- * Note that this filesystem isn't a complete implementation. In particular, it is not thread-safe.
- *
- * <p>A simple usage example:
- *
- * <pre>
- * CloudStorageFileSystemProvider.setGCloudOptions(LocalGcsHelper.options());
- * Path path = Paths.get(URI.create("gs://bucket/wednesday"));
- * thrown.expect(NoSuchFileException.class);
- * Files.newByteChannel(path);
- * </pre>
- *
- * <p>The first line ensures that the test uses the in-memory GCS instead of the real one
- * (note that you have to set the cloud options before the first usage of the gs:// prefix).
- *
  * @see <a href="https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/TESTING.md#testing-code-that-uses-storage">
  *     gcloud-java tools for testing</a>
  */

Original file line number	Diff line number	Diff line change
`@@ -83,7 +83,7 @@ public static CloudStorageOption.OpenCopy withUserMetadata(String key, String va`
`83`	`83`	`}`
`84`	`84`
`85`	`85`	`/**`
`86`		`- * Sets the block size (in bytes) when talking to the GCS server.`
	`86`	`+ * Sets the block size (in bytes) when talking to the Google Cloud Storage server.`
`87`	`87`	`*`
`88`	`88`	`* <p>The default is {@value CloudStorageFileSystem#BLOCK_SIZE_DEFAULT}.`
`89`	`89`	`*/`