[red-knot] Improve Vfs and FileSystem documentation (#11856)

Author: MichaReiser

crates/ruff_db/src/file_system.rs

@@ -13,11 +13,14 @@ mod os;
 
 pub type Result<T> = std::io::Result<T>;
 
-/// A file system that can be used to read and write files.
+/// An abstraction over `std::fs` with features tailored to Ruff's needs.
 ///
-/// The file system is agnostic to the actual storage medium, it could be a real file system, a combination
-/// of a real file system and an in-memory file system in the case of an LSP where unsaved changes are stored in memory,
-/// or an all in-memory file system for testing.
+/// Provides a file system agnostic API to interact with files and directories.
+/// Abstracting the file system operations enables:
+///
+/// * Accessing unsaved or even untitled files in the LSP use case
+/// * Testing with an in-memory file system
+/// * Running Ruff in a WASM environment without needing to stub out the full `std::fs` API.
 pub trait FileSystem {
     /// Reads the metadata of the file or directory at `path`.
     fn metadata(&self, path: &FileSystemPath) -> Result<Metadata>;

crates/ruff_db/src/vfs.rs

@@ -38,7 +38,7 @@ pub struct Vfs {
 
 #[derive(Default)]
 struct VfsInner {
-    /// Lookup table that maps the path to a salsa interned [`VfsFile`] instance.
+    /// Lookup table that maps [`VfsPath`]s to salsa interned [`VfsFile`] instances.
     ///
     /// The map also stores entries for files that don't exist on the file system. This is necessary
     /// so that queries that depend on the existence of a file are re-executed when the file is created.
@@ -93,7 +93,7 @@ impl Vfs {
             })
     }
 
-    /// Lookups a vendored file by its path. Returns `Some` if a vendored file for the given path
+    /// Looks up a vendored file by its path. Returns `Some` if a vendored file for the given path
     /// exists and `None` otherwise.
     pub fn vendored(&self, db: &dyn Db, path: &VendoredPath) -> Option<VfsFile> {
         let file = match self
@@ -144,7 +144,7 @@ impl Vfs {
     }
 
     /// Creates a salsa like snapshot of the files. The instances share
-    /// the same path to file mapping.
+    /// the same path-to-file mapping.
     pub fn snapshot(&self) -> Self {
         Self {
             inner: self.inner.clone(),