diff options
| -rw-r--r-- | crates/vfs/src/lib.rs | 51 |
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. |
| 37 | mod vfs_path; | 34 | //! |
| 38 | mod 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 | ||
| 39 | mod anchored_path; | 40 | mod anchored_path; |
| 40 | pub mod file_set; | 41 | pub mod file_set; |
| 41 | pub mod loader; | 42 | pub mod loader; |
| 43 | mod path_interner; | ||
| 44 | mod vfs_path; | ||
| 42 | 45 | ||
| 43 | use std::{fmt, mem}; | 46 | use std::{fmt, mem}; |
| 44 | 47 | ||