docs: Update documentation to be clearer on pseudo-directory pitfalls (#980)

Author: sydney-munro

.readme-partials.yaml

@@ -72,8 +72,9 @@ custom_content: |
   always be assumed to exist, without performing any I/O. Paths without the trailing
   slash will result in an I/O operation to check a file is present in that "directory".
   This allows you to do path manipulation in the same manner as you would with the normal UNIX file
-  system implementation. You can disable this feature with
-  `CloudStorageConfiguration.usePseudoDirectories()`.
+  system implementation. Using this feature with buckets or "directory" paths that do not exist
+  is not recommended, as at the time I/O is performed the failure may not be handled gracefully.
+  You can disable this feature with `CloudStorageConfiguration.usePseudoDirectories()`.
 
   #### Complete source code
 

README.md

@@ -174,8 +174,9 @@ path that includes a trailing slash, will be considered a directory. It will
 always be assumed to exist, without performing any I/O. Paths without the trailing
 slash will result in an I/O operation to check a file is present in that "directory".
 This allows you to do path manipulation in the same manner as you would with the normal UNIX file
-system implementation. You can disable this feature with
-`CloudStorageConfiguration.usePseudoDirectories()`.
+system implementation. Using this feature with buckets or "directory" paths that do not exist
+is not recommended, as at the time I/O is performed the failure may not be handled gracefully.
+You can disable this feature with `CloudStorageConfiguration.usePseudoDirectories()`.
 
 #### Complete source code
 

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

@@ -56,7 +56,8 @@ public abstract class CloudStorageConfiguration {
    * directories.
    *
    * <p>With this feature, if file "foo/bar.txt" exists then both "foo" and "foo/" will be treated
-   * as if they were existing directories.
+   * as if they were existing directories. On path construction no I/O will be performed, bucket and
+   * "directory" will treated as if they exist.
    */
   public abstract boolean usePseudoDirectories();