1 files changed, 90 insertions, 4 deletions

diff --git a/crates/vfs/src/vfs_path.rs b/crates/vfs/src/vfs_path.rs
index bd14911c9..2b3d7fd84 100644
--- a/crates/vfs/src/vfs_path.rs
+++ b/crates/vfs/src/vfs_path.rs
@@ -3,25 +3,37 @@ use std::fmt;
 
 use paths::{AbsPath, AbsPathBuf};
 
+/// Path in [`Vfs`].
+///
 /// Long-term, we want to support files which do not reside in the file-system,
-/// so we treat VfsPaths as opaque identifiers.
+/// so we treat `VfsPath`s as opaque identifiers.
+///
+/// [`Vfs`]: crate::Vfs
 #[derive(Clone, Ord, PartialOrd, Eq, PartialEq, Hash)]
 pub struct VfsPath(VfsPathRepr);
 
 impl VfsPath {
-    /// Creates an "in-memory" path from `/`-separates string.
+    /// Creates an "in-memory" path from `/`-separated string.
+    ///
     /// This is most useful for testing, to avoid windows/linux differences
+    ///
+    /// # Panics
+    ///
+    /// Panics if `path` does not start with `'/'`.
     pub fn new_virtual_path(path: String) -> VfsPath {
         assert!(path.starts_with('/'));
         VfsPath(VfsPathRepr::VirtualPath(VirtualPath(path)))
     }
 
+    /// Returns the `AbsPath` representation of `self` if `self` is on the file system.
     pub fn as_path(&self) -> Option<&AbsPath> {
         match &self.0 {
             VfsPathRepr::PathBuf(it) => Some(it.as_path()),
             VfsPathRepr::VirtualPath(_) => None,
         }
     }
+
+    /// Creates a new `VfsPath` with `path` adjoined to `self`.
     pub fn join(&self, path: &str) -> Option<VfsPath> {
         match &self.0 {
             VfsPathRepr::PathBuf(it) => {
@@ -34,12 +46,30 @@ impl VfsPath {
             }
         }
     }
+
+    /// Remove the last component of `self` if there is one.
+    ///
+    /// If `self` has no component, returns `false`; else returns `true`.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use vfs::{AbsPathBuf, VfsPath};
+    /// let mut path = VfsPath::from(AbsPathBuf::assert("/foo/bar".into()));
+    /// assert!(path.pop());
+    /// assert_eq!(path, VfsPath::from(AbsPathBuf::assert("/foo".into())));
+    /// assert!(path.pop());
+    /// assert_eq!(path, VfsPath::from(AbsPathBuf::assert("/".into())));
+    /// assert!(!path.pop());
+    /// ```
     pub fn pop(&mut self) -> bool {
         match &mut self.0 {
             VfsPathRepr::PathBuf(it) => it.pop(),
             VfsPathRepr::VirtualPath(it) => it.pop(),
         }
     }
+
+    /// Returns `true` if `other` is a prefix of `self`.
     pub fn starts_with(&self, other: &VfsPath) -> bool {
         match (&self.0, &other.0) {
             (VfsPathRepr::PathBuf(lhs), VfsPathRepr::PathBuf(rhs)) => lhs.starts_with(rhs),
@@ -48,6 +78,10 @@ impl VfsPath {
             (VfsPathRepr::VirtualPath(_), _) => false,
         }
     }
+
+    /// Returns the `VfsPath` without its final component, if there is one.
+    ///
+    /// Returns [`None`] if the path is a root or prefix.
     pub fn parent(&self) -> Option<VfsPath> {
         let mut parent = self.clone();
         if parent.pop() {
@@ -57,6 +91,7 @@ impl VfsPath {
         }
     }
 
+    /// Returns `self`'s base name and file extension.
     pub fn name_and_extension(&self) -> Option<(&str, Option<&str>)> {
         match &self.0 {
             VfsPathRepr::PathBuf(p) => Some((
@@ -67,7 +102,14 @@ impl VfsPath {
         }
     }
 
-    // Don't make this `pub`
+    /// **Don't make this `pub`**
+    ///
+    /// Encode the path in the given buffer.
+    ///
+    /// The encoding will be `0` if [`AbsPathBuf`], `1` if [`VirtualPath`], followed
+    /// by `self`'s representation.
+    ///
+    /// Note that this encoding is dependent on the operating system.
     pub(crate) fn encode(&self, buf: &mut Vec<u8>) {
         let tag = match &self.0 {
             VfsPathRepr::PathBuf(_) => 0,
@@ -224,6 +266,7 @@ mod windows_paths {
     }
 }
 
+/// Internal, private representation of [`VfsPath`].
 #[derive(Clone, Ord, PartialOrd, Eq, PartialEq, Hash)]
 enum VfsPathRepr {
     PathBuf(AbsPathBuf),
@@ -260,13 +303,34 @@ impl fmt::Debug for VfsPathRepr {
     }
 }
 
+/// `/`-separated virtual path.
+///
+/// This is used to describe files that do not reside on the file system.
 #[derive(Debug, Clone, Ord, PartialOrd, Eq, PartialEq, Hash)]
 struct VirtualPath(String);
 
 impl VirtualPath {
+    /// Returns `true` if `other` is a prefix of `self` (as strings).
     fn starts_with(&self, other: &VirtualPath) -> bool {
         self.0.starts_with(&other.0)
     }
+
+    /// Remove the last component of `self`.
+    ///
+    /// This will find the last `'/'` in `self`, and remove everything after it,
+    /// including the `'/'`.
+    ///
+    /// If `self` contains no `'/'`, returns `false`; else returns `true`.
+    ///
+    /// # Example
+    ///
+    /// ```rust,ignore
+    /// let mut path = VirtualPath("/foo/bar".to_string());
+    /// path.pop();
+    /// assert_eq!(path.0, "/foo");
+    /// path.pop();
+    /// assert_eq!(path.0, "");
+    /// ```
     fn pop(&mut self) -> bool {
         let pos = match self.0.rfind('/') {
             Some(pos) => pos,
@@ -275,6 +339,17 @@ impl VirtualPath {
         self.0 = self.0[..pos].to_string();
         true
     }
+
+    /// Append the given *relative* path `path` to `self`.
+    ///
+    /// This will resolve any leading `"../"` in `path` before appending it.
+    ///
+    /// Returns [`None`] if `path` has more leading `"../"` than the number of
+    /// components in `self`.
+    ///
+    /// # Notes
+    ///
+    /// In practice, appending here means `self/path` as strings.
     fn join(&self, mut path: &str) -> Option<VirtualPath> {
         let mut res = self.clone();
         while path.starts_with("../") {
@@ -287,7 +362,18 @@ impl VirtualPath {
         Some(res)
     }
 
-    pub(crate) fn name_and_extension(&self) -> Option<(&str, Option<&str>)> {
+    /// Returns `self`'s base name and file extension.
+    ///
+    /// # Returns
+    /// - `None` if `self` ends with `"//"`.
+    /// - `Some((name, None))` if `self`'s base contains no `.`, or only one `.` at
+    /// the start.
+    /// - `Some((name, Some(extension))` else.
+    ///
+    /// # Note
+    /// The extension will not contains `.`. This means `"/foo/bar.baz.rs"` will
+    /// return `Some(("bar.baz", Some("rs"))`.
+    fn name_and_extension(&self) -> Option<(&str, Option<&str>)> {
         let file_path = if self.0.ends_with('/') { &self.0[..&self.0.len() - 1] } else { &self.0 };
         let file_name = match file_path.rfind('/') {
             Some(position) => &file_path[position + 1..],