aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--crates/vfs/src/lib.rs51
1 files changed, 27 insertions, 24 deletions
diff --git a/crates/vfs/src/lib.rs b/crates/vfs/src/lib.rs
index 9cf2afd33..2b7b14524 100644
--- a/crates/vfs/src/lib.rs
+++ b/crates/vfs/src/lib.rs
@@ -2,43 +2,46 @@
2//! 2//!
3//! VFS stores all files read by rust-analyzer. Reading file contents from VFS 3//! VFS stores all files read by rust-analyzer. Reading file contents from VFS
4//! always returns the same contents, unless VFS was explicitly modified with 4//! always returns the same contents, unless VFS was explicitly modified with
5//! `set_file_contents`. All changes to VFS are logged, and can be retrieved via 5//! [`set_file_contents`]. All changes to VFS are logged, and can be retrieved via
6//! `take_changes` method. The pack of changes is then pushed to `salsa` and 6//! [`take_changes`] method. The pack of changes is then pushed to `salsa` and
7//! triggers incremental recomputation. 7//! triggers incremental recomputation.
8//! 8//!
9//! Files in VFS are identified with `FileId`s -- interned paths. The notion of 9//! Files in VFS are identified with [`FileId`]s -- interned paths. The notion of
10//! the path, `VfsPath` is somewhat abstract: at the moment, it is represented 10//! the path, [`VfsPath`] is somewhat abstract: at the moment, it is represented
11//! as an `std::path::PathBuf` internally, but this is an implementation detail. 11//! as an [`std::path::PathBuf`] internally, but this is an implementation detail.
12//! 12//!
13//! VFS doesn't do IO or file watching itself. For that, see the `loader` 13//! VFS doesn't do IO or file watching itself. For that, see the [`loader`]
14//! module. `loader::Handle` is an object-safe trait which abstracts both file 14//! module. [`loader::Handle`] is an object-safe trait which abstracts both file
15//! loading and file watching. `Handle` is dynamically configured with a set of 15//! loading and file watching. [`Handle`] is dynamically configured with a set of
16//! directory entries which should be scanned and watched. `Handle` then 16//! directory entries which should be scanned and watched. [`Handle`] then
17//! asynchronously pushes file changes. Directory entries are configured in 17//! asynchronously pushes file changes. Directory entries are configured in
18//! free-form via list of globs, it's up to the `Handle` to interpret the globs 18//! free-form via list of globs, it's up to the [`Handle`] to interpret the globs
19//! in any specific way. 19//! in any specific way.
20//! 20//!
21//! A simple `WalkdirLoaderHandle` is provided, which doesn't implement watching 21//! VFS stores a flat list of files. [`file_set::FileSet`] can partition this list
22//! and just scans the directory using walkdir. 22//! of files into disjoint sets of files. Traversal-like operations (including
23//! 23//! getting the neighbor file by the relative path) are handled by the [`FileSet`].
24//! VFS stores a flat list of files. `FileSet` can partition this list of files 24//! [`FileSet`]s are also pushed to salsa and cause it to re-check `mod foo;`
25//! into disjoint sets of files. Traversal-like operations (including getting
26//! the neighbor file by the relative path) are handled by the `FileSet`.
27//! `FileSet`s are also pushed to salsa and cause it to re-check `mod foo;`
28//! declarations when files are created or deleted. 25//! declarations when files are created or deleted.
29//! 26//!
30//! `file_set::FileSet` and `loader::Entry` play similar, but different roles. 27//! [`FileSet`] and [`loader::Entry`] play similar, but different roles.
31//! Both specify the "set of paths/files", one is geared towards file watching, 28//! Both specify the "set of paths/files", one is geared towards file watching,
32//! the other towards salsa changes. In particular, single `file_set::FileSet` 29//! the other towards salsa changes. In particular, single [`FileSet`]
33//! may correspond to several `loader::Entry`. For example, a crate from 30//! may correspond to several [`loader::Entry`]. For example, a crate from
34//! crates.io which uses code generation would have two `Entries` -- for sources 31//! crates.io which uses code generation would have two [`Entries`] -- for sources
35//! in `~/.cargo`, and for generated code in `./target/debug/build`. It will 32//! in `~/.cargo`, and for generated code in `./target/debug/build`. It will
36//! have a single `FileSet` which unions the two sources. 33//! have a single [`FileSet`] which unions the two sources.
37mod vfs_path; 34//!
38mod path_interner; 35//! [`set_file_contents`]: Vfs::set_file_contents
36//! [`take_changes`]: Vfs::take_changes
37//! [`FileSet`]: file_set::FileSet
38//! [`Handle`]: loader::Handle
39//! [`Entries`]: loader::Entry
39mod anchored_path; 40mod anchored_path;
40pub mod file_set; 41pub mod file_set;
41pub mod loader; 42pub mod loader;
43mod path_interner;
44mod vfs_path;
42 45
43use std::{fmt, mem}; 46use std::{fmt, mem};
44 47