Merge #7257

7257: vfs documentation r=matklad a=arnaudgolfouse

This documents every item in the `vfs` crate, except for a few private, windows-specific items.

Co-authored-by: Arnaud <[email protected]>

1 files changed, 14 insertions, 0 deletions

diff --git a/crates/vfs/src/path_interner.rs b/crates/vfs/src/path_interner.rs
index 4f70d61e8..2189e5e25 100644
--- a/crates/vfs/src/path_interner.rs
+++ b/crates/vfs/src/path_interner.rs
@@ -5,6 +5,7 @@ use rustc_hash::FxHashMap;
 
 use crate::{FileId, VfsPath};
 
+/// Structure to map between [`VfsPath`] and [`FileId`].
 #[derive(Default)]
 pub(crate) struct PathInterner {
     map: FxHashMap<VfsPath, FileId>,
@@ -12,9 +13,17 @@ pub(crate) struct PathInterner {
 }
 
 impl PathInterner {
+    /// Get the id corresponding to `path`.
+    ///
+    /// If `path` does not exists in `self`, returns [`None`].
     pub(crate) fn get(&self, path: &VfsPath) -> Option<FileId> {
         self.map.get(path).copied()
     }
+
+    /// Insert `path` in `self`.
+    ///
+    /// - If `path` already exists in `self`, returns its associated id;
+    /// - Else, returns a newly allocated id.
     pub(crate) fn intern(&mut self, path: VfsPath) -> FileId {
         if let Some(id) = self.get(&path) {
             return id;
@@ -25,6 +34,11 @@ impl PathInterner {
         id
     }
 
+    /// Returns the path corresponding to `id`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `id` does not exists in `self`.
     pub(crate) fn lookup(&self, id: FileId) -> &VfsPath {
         &self.vec[id.0 as usize]
     }