aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--crates/vfs/src/lib.rs46
1 files changed, 26 insertions, 20 deletions
diff --git a/crates/vfs/src/lib.rs b/crates/vfs/src/lib.rs
index 9999bbb9e..8c8d1114d 100644
--- a/crates/vfs/src/lib.rs
+++ b/crates/vfs/src/lib.rs
@@ -2,40 +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//! VFS stores a flat list of files. `FileSet` can partition this list of files 21//! VFS stores a flat list of files. [`FileSet`] can partition this list of files
22//! into disjoint sets of files. Traversal-like operations (including getting 22//! into disjoint sets of files. Traversal-like operations (including getting
23//! the neighbor file by the relative path) are handled by the `FileSet`. 23//! the neighbor file by the relative path) are handled by the [`FileSet`].
24//! `FileSet`s are also pushed to salsa and cause it to re-check `mod foo;` 24//! [`FileSet`]s are also pushed to salsa and cause it to re-check `mod foo;`
25//! declarations when files are created or deleted. 25//! declarations when files are created or deleted.
26//! 26//!
27//! `file_set::FileSet` and `loader::Entry` play similar, but different roles. 27//! [`file_set::FileSet`] and [`loader::Entry`] play similar, but different roles.
28//! 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,
29//! the other towards salsa changes. In particular, single `file_set::FileSet` 29//! the other towards salsa changes. In particular, single [`file_set::FileSet`]
30//! may correspond to several `loader::Entry`. For example, a crate from 30//! may correspond to several [`loader::Entry`]. For example, a crate from
31//! 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
32//! 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
33//! have a single `FileSet` which unions the two sources. 33//! have a single [`FileSet`] which unions the two sources.
34mod vfs_path; 34//!
35mod 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
36mod anchored_path; 40mod anchored_path;
37pub mod file_set; 41pub mod file_set;
38pub mod loader; 42pub mod loader;
43mod path_interner;
44mod vfs_path;
39 45
40use std::{fmt, mem}; 46use std::{fmt, mem};
41 47