Improve FileSystem documentation (#218)

* Mentioned filesystems and paths in README

* Improved filesystems documentation

Author: fzhinkin

README.md

@@ -21,9 +21,16 @@ The library also provides interfaces representing data sources and destinations
 
 In addition to `Buffer`, the library provides an immutable sequence of bytes - `ByteString`.
 
+Also, there's an experimental filesystem support provided by `kotlinx.io.files` package. 
+The package includes `FileSystem` interface  and its implementation - `SystemFileSystem`. 
+
+`FileSystem` provides basic operations for working with files and directories.
+
+File and directory paths are represented by yet another class provided by the package - `Path`.
+
 There are two `kotlinx-io` modules:
 - [kotlinx-io-bytestring](./bytestring) - provides `ByteString`.
-- [kotlinx-io-core](./core) - provides IO primitives (`Buffer`, `Source`, `Sink`), depends on `kotlinx-io-bytestring`.
+- [kotlinx-io-core](./core) - provides IO primitives (`Buffer`, `Source`, `Sink`), filesystems support, depends on `kotlinx-io-bytestring`.
 
 ## Using in your projects
 

core/common/src/files/FileSystem.kt

@@ -10,7 +10,15 @@ import kotlinx.io.RawSink
 import kotlinx.io.RawSource
 
 /**
- * An interface providing basic operations on a filesystem.
+ * An interface providing basic operations on a filesystem, such as reading and writing files,
+ * creating directories, gathering file metadata and so on.
+ *
+ * Default implementation of this interface is [SystemFileSystem]. It provides access to files and directories
+ * on disk.
+ *
+ * The interface is sealed until API stabilization, but in the future it will allow
+ * creating custom filesystems that could be used as mocks for testing or provide
+ * access to some network resources and allow working with them as with regular files, for example.
  *
  * **This API is unstable and subject to change.**
  */
@@ -138,7 +146,8 @@ public expect val SystemFileSystem: FileSystem
 public expect val SystemTemporaryDirectory: Path
 
 /**
- * Represents information about a file or directory obtainable from a filesystem.
+ * Represents information about a file or directory obtainable from a filesystem like
+ * a type of filesystem node (is it a directory or a file?), its size, and so on.
  */
 public class FileMetadata(
     /**