@@ -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
 
 
@@ -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
 
 
@@ -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();
Original file line number	Diff line number	Diff line change
`@@ -56,7 +56,8 @@ public abstract class CloudStorageConfiguration {`
`56`	`56`	`* directories.`
`57`	`57`	`*`
`58`	`58`	`* <p>With this feature, if file "foo/bar.txt" exists then both "foo" and "foo/" will be treated`
`59`		`- * as if they were existing directories.`
	`59`	`+ * as if they were existing directories. On path construction no I/O will be performed, bucket and`
	`60`	`+ * "directory" will treated as if they exist.`
`60`	`61`	`*/`
`61`	`62`	`public abstract boolean usePseudoDirectories();`
`62`	`63`