Merge pull request square#883 from square/jwilson.0111.remote_no_go

Document that remote file systems are a bad fit
sneha1702 · Jan 11, 2021 · 3be678e · 3be678e
2 parents cf28008 + 6425f63
commit 3be678e
Showing 1 changed file with 13 additions and 14 deletions.
diff --git a/okio/src/commonMain/kotlin/okio/FileSystem.kt b/okio/src/commonMain/kotlin/okio/FileSystem.kt
@@ -22,41 +22,40 @@ import kotlin.jvm.JvmField
  * Read and write access to a hierarchical collection of files, addressed by [paths][Path]. This
  * is a natural interface to the [current computer's local file system][SYSTEM].
  *
- * Not Just the Local File System
- * ------------------------------
- *
  * Other implementations are possible:
  *
  *  * `FakeFileSystem` is an in-memory file system suitable for testing. Note that this class is
  *    included in the `okio-fakefilesystem` artifact.
  *
- *  * A ZIP file system could provide access to the contents of a `.zip` file.
- *
- *  * A remote file system could access files over the network.
+ *  * [ForwardingFileSystem] is a file system decorator. Use it to apply monitoring, encryption,
+ *    compression, or filtering to another file system.
  *
- *  * A [decorating file system][ForwardingFileSystem] could apply monitoring, encryption,
- *    compression, or filtering to another file system implementation.
+ *  * A ZIP file system could provide access to the contents of a `.zip` file.
  *
  * For improved capability and testability, consider structuring your classes to dependency inject
  * a `FileSystem` rather than using [SYSTEM] directly.
  *
- * Limited API
- * -----------
+ * Small API
+ * ---------
+ *
+ * This interface is deliberately limited in which features it supports.
  *
- * This interface is limited in which file system features it supports. Applications that need rich
- * file system features should use another API, possibly alongside this API.
+ * It is not suitable for high-latency or unreliable remote file systems. It lacks support for
+ * retries, timeouts, cancellation, and bulk operations.
  *
- * This class cannot create special file types like hard links, symlinks, pipes, or mounts. Reading
+ * It cannot create special file types like hard links, symlinks, pipes, or mounts. Reading
  * or writing these files works as if they were regular files.
  *
  * It cannot read or write file access control features like the UNIX `chmod` and Windows access
  * control lists. It does honor these controls and will fail with an [IOException] if privileges
  * are insufficient!
  *
- * It cannot lock files, or query which files are locked.
+ * It cannot lock files or check which files are locked.
  *
  * It cannot watch the file system for changes.
  *
+ * Applications that need rich file system features should use another API!
+ *
  * Multiplatform
  * -------------
  *