From f61f3671a662d5760f3f19c029929f48e511c678 Mon Sep 17 00:00:00 2001
From: Lucien Greathouse <me@lpghatguy.com>
Date: Tue, 10 Mar 2020 17:57:57 -0700
Subject: [PATCH] Choose 'memofs' as the vfs name

---
 vfs/Cargo.toml |  2 +-
 vfs/README.md  | 19 ++++++++++++++++---
 vfs/README.tpl |  7 +++++++
 vfs/src/lib.rs | 26 +++++++++++++++++++++++++-
 4 files changed, 49 insertions(+), 5 deletions(-)
 create mode 100644 vfs/README.tpl

diff --git a/vfs/Cargo.toml b/vfs/Cargo.toml
index 38b7cbfd..96be15c7 100644
--- a/vfs/Cargo.toml
+++ b/vfs/Cargo.toml
@@ -5,7 +5,7 @@ authors = ["Lucien Greathouse <me@lpghatguy.com>"]
 edition = "2018"
 readme = "README.md"
 license = "MIT"
-homepage = "https://github.com/rojo-rbx/rojo"
+homepage = "https://github.com/rojo-rbx/rojo/tree/master/vfs"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
diff --git a/vfs/README.md b/vfs/README.md
index 981daa26..4659ce3d 100644
--- a/vfs/README.md
+++ b/vfs/README.md
@@ -1,5 +1,18 @@
-# [vfs]
-Name pending. Implementation of a virtual filesystem with a configurable backend and file watching.
+# vfs
+Implementation of a virtual filesystem with a configurable backend and file watching.
+
+memofs is currently an unstable minimum viable library. Its primary consumer is [Rojo](https://github.com/rojo-rbx/rojo), a build system for Roblox.
+
+### Current Features
+* API similar to `std::fs`
+* Configurable backends
+    * `StdBackend`, which uses `std::fs` and the `notify` crate
+    * `NoopBackend`, which always throws errors
+    * `InMemoryFs`, a simple in-memory filesystem useful for testing
+
+### Future Features
+* Hash-based hierarchical memoization keys (hence the name)
+* Configurable caching (write-through, write-around, write-back)
 
 ## License
-[vfs] is available under the terms of the MIT license. See [LICENSE.txt](LICENSE.txt) or <https://opensource.org/licenses/MIT> for more details.
\ No newline at end of file
+memofs is available under the terms of the MIT license. See [LICENSE.txt](LICENSE.txt) or <https://opensource.org/licenses/MIT> for more details.
diff --git a/vfs/README.tpl b/vfs/README.tpl
new file mode 100644
index 00000000..b8129a25
--- /dev/null
+++ b/vfs/README.tpl
@@ -0,0 +1,7 @@
+# {{crate}}
+[![Crates.io](https://img.shields.io/crates/v/memofs.svg)](https://crates.io/crates/memofs)
+
+{{readme}}
+
+## License
+memofs is available under the terms of the MIT license. See [LICENSE.txt](LICENSE.txt) or <https://opensource.org/licenses/MIT> for more details.
\ No newline at end of file
diff --git a/vfs/src/lib.rs b/vfs/src/lib.rs
index 8aede061..cbdc63da 100644
--- a/vfs/src/lib.rs
+++ b/vfs/src/lib.rs
@@ -1,3 +1,20 @@
+/*!
+Implementation of a virtual filesystem with a configurable backend and file watching.
+
+memofs is currently an unstable minimum viable library. Its primary consumer is [Rojo](https://github.com/rojo-rbx/rojo), a build system for Roblox.
+
+## Current Features
+* API similar to `std::fs`
+* Configurable backends
+    * `StdBackend`, which uses `std::fs` and the `notify` crate
+    * `NoopBackend`, which always throws errors
+    * `InMemoryFs`, a simple in-memory filesystem useful for testing
+
+## Future Features
+* Hash-based hierarchical memoization keys (hence the name)
+* Configurable caching (write-through, write-around, write-back)
+*/
+
 mod in_memory_fs;
 mod noop_backend;
 mod snapshot;
@@ -178,6 +195,10 @@ impl VfsInner {
 }
 
 /// A virtual filesystem with a configurable backend.
+///
+/// All operations on the Vfs take a lock on an internal backend. For performing
+/// large batches of operations, it might be more performant to call `lock()`
+/// and use [`VfsLock`](struct.VfsLock.html) instead.
 pub struct Vfs {
     inner: Mutex<VfsInner>,
 }
@@ -199,6 +220,7 @@ impl Vfs {
         }
     }
 
+    /// Manually lock the Vfs, useful for large batches of operations.
     pub fn lock(&self) -> VfsLock<'_> {
         VfsLock {
             inner: self.inner.lock().unwrap(),
@@ -286,7 +308,9 @@ impl Vfs {
     }
 }
 
-/// A locked handle to a `Vfs`, created by `Vfs::lock`.
+/// A locked handle to a [`Vfs`](struct.Vfs.html), created by `Vfs::lock`.
+///
+/// Implements roughly the same API as [`Vfs`](struct.Vfs.html).
 pub struct VfsLock<'a> {
     inner: MutexGuard<'a, VfsInner>,
 }