Skip to content

Commit

Permalink
[red-knot] Improve Vfs and FileSystem documentation (#11856)
Browse files Browse the repository at this point in the history
  • Loading branch information
MichaReiser authored Jun 13, 2024
1 parent 73370fe commit c5bc368
Show file tree
Hide file tree
Showing 2 changed files with 10 additions and 7 deletions.
11 changes: 7 additions & 4 deletions crates/ruff_db/src/file_system.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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>;
Expand Down
6 changes: 3 additions & 3 deletions crates/ruff_db/src/vfs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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(),
Expand Down

0 comments on commit c5bc368

Please sign in to comment.