chore: trim verbose VFS and host comments

Keep short module docs and non-obvious behavior notes; drop fork
narratives, outdated identity comments, and redundant restatements.

Author: hongjr03

Cargo.toml

@@ -138,7 +138,7 @@ utils = { workspace = true, features = ["test-support"] }
 
 [features]
 default = ["server-file-watcher"]
-# OS notify-based server file watching (disable for wasm / headless client-only).
+# Server OS file watching (off for wasm).
 server-file-watcher = ["vfs/notify-backend"]
 profile-trace = ["dep:tracing-chrome"]
 user-config-schema = ["dep:schemars"]

crates/project-model/src/lib.rs

@@ -62,10 +62,10 @@ pub struct WorkspaceRoot {
     pub extra_files: Vec<AbsPathBuf>,
     /// Include/search roots loaded as headers and passed to preprocessing.
     pub include_dirs: Vec<AbsPathBuf>,
-    /// Absolute directory prefixes excluded from directory loads (expanded from
-    /// manifest exclude globs before the loader sees them).
+    /// Exclude directory prefixes for loader `Directories` (from manifest
+    /// globs).
     pub exclude_prefixes: Vec<AbsPathBuf>,
-    /// Glob matcher retained for FileSet classification of opened files.
+    /// Exclude globs for FileSet classification.
     pub exclude_globs: Option<PathGlobMatcher>,
 }
 
@@ -459,11 +459,8 @@ fn compile_manifest_globs(
         .with_context(|| format!("failed to compile manifest {field} glob patterns"))
 }
 
-/// Expand exclude globs into absolute directory prefixes for the loader.
-///
-/// Patterns that are pure wildcards (e.g. `**/*.sv`) are skipped here; those
-/// still participate in FileSet classification via
-/// [`WorkspaceRoot::exclude_globs`].
+/// Expand exclude globs to directory prefixes; skip pure wildcards (e.g.
+/// `**/*.sv`).
 fn exclude_prefixes_from_patterns(
     workspace_root: &AbsPathBuf,
     patterns: &[String],
@@ -664,8 +661,6 @@ pub fn get_workspace_folder(
                     exclude_paths.push(excl.clone());
                 }
             }
-            // Manifest exclude globs are expanded to directory prefixes before
-            // the loader (r-a-shaped Directories has no glob field).
             exclude_paths.extend(root.exclude_prefixes.iter().cloned());
             sort_and_remove_subfolders(&mut exclude_paths);
             let mut include = Vec::new();
@@ -700,9 +695,6 @@ pub fn get_workspace_folder(
                 load_entries.push(vfs::loader::Entry::Files(source_files));
             }
 
-            // Recursive loads: include_dirs + pure root matchers.
-            // Glob source patterns (e.g. `rtl/*.sv`) are expanded to Entry::Files
-            // so the r-a-style loader does not need glob semantics.
             let mut directory_include = root.include_dirs.clone();
             if !root.source_directories.is_empty() {
                 if root.source_directories.prefers_recursive_directory_load() {
@@ -1305,7 +1297,6 @@ include_dirs = []
         let (load, _, _, _) = get_workspace_folder(&model.workspaces, &[]);
 
         assert!(errors.is_empty(), "{errors:#?}");
-        // Shallow globs expand to Entry::Files (loader has no glob depth rules).
         let files = match load.iter().find_map(|entry| match entry {
             vfs::loader::Entry::Files(files) => Some(files),
             _ => None,
@@ -1432,17 +1423,12 @@ exclude = ["**/*_bb.v"]
         let (load, _, source_root_config, _) = get_workspace_folder(&model.workspaces, &[]);
 
         assert!(errors.is_empty(), "{errors:#?}");
-        // Filename globs like `**/*_bb.v` cannot be expressed as loader directory
-        // prefixes (r-a-shaped Directories). They still classify via FileSet.
         let dirs = match &load[0] {
             vfs::loader::Entry::Directories(dirs) => dirs,
             other => panic!("expected directory loader entry, got {other:?}"),
         };
         assert!(dirs.contains_file(top.as_path()));
-        assert!(
-            dirs.contains_file(blackbox.as_path()),
-            "loader may still discover filename-glob matches; FileSet drops them"
-        );
+        assert!(dirs.contains_file(blackbox.as_path()));
 
         let mut vfs = Vfs::default();
         for file in [&top, &blackbox] {

crates/vfs/src/dummy.rs

@@ -1,11 +1,4 @@
-//! In-memory / no-OS loader used when the notify backend is disabled (e.g.
-//! wasm).
-//!
-//! Does not scan the real filesystem or install watchers. Configuration scans
-//! complete immediately with empty file batches so the host can still drive
-//! readiness from Progress. File contents must come from the client (mem docs)
-//! or explicit `invalidate` / `load_sync` against whatever FS the host
-//! provides.
+//! Loader with no OS file watching (e.g. wasm).
 
 use std::fmt;
 
@@ -32,7 +25,6 @@ impl loader::Handle for DummyHandle {
             dir: None,
             config_version,
         });
-        // No disk scan: report empty loads so Progress can finish.
         for _ in &config.load {
             let _ = self.sender.send(loader::Message::Loaded { files: Vec::new() });
         }

crates/vfs/src/file_set.rs

@@ -5,11 +5,7 @@ use utils::paths::{AbsPath, AbsPathBuf};
 
 use crate::{AnchoredPath, FileId, Vfs, VfsPath, path_glob::PathGlobMatcher};
 
-/// Bidirectional path map for a single source root.
-///
-/// A `FileSet` stores the path spelling selected during source-root
-/// partitioning. That spelling may be a VFS alias rather than the primary path
-/// if the alias is the one that belongs to this root.
+/// Files belonging to one source root.
 #[derive(Debug, Default, Clone, Eq, PartialEq)]
 pub struct FileSet {
     files: FxHashMap<VfsPath, FileId>,
@@ -50,35 +46,23 @@ impl FileSet {
     }
 }
 
-/// Rules for partitioning VFS files into ordered source roots.
-///
-/// Root order is significant. For one VFS file with several aliases,
-/// classification evaluates every alias and chooses the earliest non-ignored
-/// root. Within a single alias, normal prefix matching still picks the most
-/// specific configured root.
+/// Partitions VFS files into ordered source roots (earlier roots win).
 #[derive(Debug)]
 pub struct FileSetConfig {
-    // Number of sets that can partition into.
-    // This should be `self.map.len() + 1` for files that don't fit in any defined set.
+    /// `map` size + 1 for files that match no root.
     len: usize,
-    // Encoded paths -> sets they belong to.
     map: fst::Map<Vec<u8>>,
     filters: Vec<FileSetFilter>,
 }
 
-/// A source-root partition plus the subset that matched semantic source rules.
+/// One partition: all files in the root, plus optional semantic source subset.
 #[derive(Debug, Default, Clone, Eq, PartialEq)]
 pub struct PartitionedFileSet {
     pub file_set: FileSet,
     pub source_files: Option<FxHashSet<FileId>>,
 }
 
-/// Matcher used separately for source classification, directory scans, and
-/// include/search roots.
-///
-/// Keeping those roles separate lets exact source files participate in source
-/// ownership without forcing the loader or watcher to scan their parent
-/// directories recursively.
+/// Path include rule: recursive roots and/or a glob.
 #[derive(Debug, Clone, Eq, PartialEq, Hash)]
 pub struct PathMatcher {
     scan_roots: Vec<AbsPathBuf>,
@@ -126,11 +110,8 @@ impl PathMatcher {
         self.scan_roots.iter()
     }
 
-    /// Whether the loader may use recursive `Directories` for this matcher.
-    ///
-    /// - `AllUnderRoots` → yes
-    /// - Glob patterns that contain `**` (e.g. `rtl/**`) → yes (prefix roots)
-    /// - Shallow globs like `rtl/*.sv` → no; expand to `Entry::Files` instead
+    /// True if this can be loaded as recursive directory roots (`**` globs or
+    /// plain roots).
     pub fn prefers_recursive_directory_load(&self) -> bool {
         match &self.kind {
             PathMatcherKind::AllUnderRoots => true,
@@ -140,9 +121,7 @@ impl PathMatcher {
         }
     }
 
-    /// Walk `scan_roots` and collect absolute files that match this matcher and
-    /// one of `extensions` (no leading dot). Used to expand shallow globs like
-    /// `rtl/*.sv` without putting glob logic inside the loader.
+    /// Files under `scan_roots` matching this rule and `extensions`.
     pub fn collect_matching_files(&self, extensions: &[&str]) -> Vec<AbsPathBuf> {
         let mut files = Vec::new();
         for root in &self.scan_roots {
@@ -265,8 +244,6 @@ impl FileSetConfig {
         primary_path: &'a VfsPath,
         scratch_space: &mut Vec<u8>,
     ) -> (usize, &'a VfsPath) {
-        // Path identity aliases were removed with the r-a VFS fork; classify the
-        // primary interned spelling only.
         (self.classify(primary_path, scratch_space), primary_path)
     }
 

crates/vfs/src/lib.rs

@@ -1,47 +1,12 @@
-//! Owned fork of rust-analyzer's virtual file system (tinymist-style).
+//! Virtual file system: interned paths, content change log, and loader
+//! interface.
 //!
-//! Upstream: <https://github.com/rust-lang/rust-analyzer/tree/master/crates/vfs>
-//!
-//! # Virtual File System
-//!
-//! VFS records all file changes pushed to it via [`set_file_contents`].
-//! As such it only ever stores changes, not the actual content of a file at any
-//! given moment. All file changes are logged, and can be retrieved via
-//! [`take_changes`] method. The pack of changes is then pushed to `salsa` and
-//! triggers incremental recomputation.
-//!
-//! Files in VFS are identified with [`FileId`]s -- interned paths. The notion
-//! of the path, [`VfsPath`] is somewhat abstract: at the moment, it is
-//! represented as an [`std::path::PathBuf`] internally, but this is an
-//! implementation detail.
-//!
-//! VFS doesn't do IO or file watching itself. For that, see the [`loader`]
-//! module. [`loader::Handle`] is an object-safe trait which abstracts both file
-//! loading and file watching. [`Handle`] is dynamically configured with a set
-//! of directory entries which should be scanned and watched. [`Handle`] then
-//! asynchronously pushes file changes. Directory entries are configured in
-//! free-form via list of globs, it's up to the [`Handle`] to interpret the
-//! globs in any specific way.
-//!
-//! VFS stores a flat list of files. [`file_set::FileSet`] can partition this
-//! list of files into disjoint sets of files. Traversal-like operations
-//! (including getting the neighbor file by the relative path) are handled by
-//! the [`FileSet`]. [`FileSet`]s are also pushed to salsa and cause it to
-//! re-check `mod foo;` declarations when files are created or deleted.
-//!
-//! [`FileSet`] and [`loader::Entry`] play similar, but different roles.
-//! Both specify the "set of paths/files", one is geared towards file watching,
-//! the other towards salsa changes. In particular, single [`FileSet`]
-//! may correspond to several [`loader::Entry`]. For example, a crate from
-//! crates.io which uses code generation would have two [`Entries`] -- for
-//! sources in `~/.cargo`, and for generated code in `./target/debug/build`. It
-//! will have a single [`FileSet`] which unions the two sources.
+//! Based on rust-analyzer's `vfs` crate
+//! (<https://github.com/rust-lang/rust-analyzer/tree/master/crates/vfs>).
+//! IO and watching live in [`loader`] backends ([`notify`], [`dummy`]).
 //!
 //! [`set_file_contents`]: Vfs::set_file_contents
 //! [`take_changes`]: Vfs::take_changes
-//! [`FileSet`]: file_set::FileSet
-//! [`Handle`]: loader::Handle
-//! [`Entries`]: loader::Entry
 
 mod anchored_path;
 pub mod dummy;
@@ -81,12 +46,9 @@ fn hash_once<Hasher: std::hash::Hasher + Default>(thing: impl std::hash::Hash) -
     h.finish()
 }
 
-/// Handle to a file in [`Vfs`]
-///
-/// Most functions in rust-analyzer use this when they need to refer to a file.
+/// Interned file identity in [`Vfs`].
 #[derive(Copy, Clone, Debug, Ord, PartialOrd, Eq, PartialEq, Hash)]
 pub struct FileId(u32);
-// pub struct FileId(NonMaxU32);
 
 impl FileId {
     const MAX: u32 = 0x7fff_ffff;
@@ -166,7 +128,7 @@ impl ChangedFile {
         }
     }
 
-    /// UTF-8 file text for analysis; invalid UTF-8 becomes empty.
+    /// UTF-8 text; invalid UTF-8 becomes empty.
     pub fn text(&self) -> Option<triomphe::Arc<str>> {
         let bytes = match &self.change {
             Change::Create(bytes, _) | Change::Modify(bytes, _) => bytes.as_slice(),
@@ -176,29 +138,25 @@ impl ChangedFile {
         Some(triomphe::Arc::<str>::from(text))
     }
 
-    /// Bytes for Create/Modify; `None` for Delete.
     pub fn contents(&self) -> Option<&[u8]> {
         match &self.change {
             Change::Create(bytes, _) | Change::Modify(bytes, _) => Some(bytes.as_slice()),
             Change::Delete => None,
         }
     }
 
-    /// Test/host helper: create a file with UTF-8 text contents.
     pub fn create(file_id: FileId, text: impl AsRef<str>) -> Self {
         let bytes = text.as_ref().as_bytes().to_vec();
         let hash = hash_once::<FxHasher>(&*bytes);
         Self { file_id, change: Change::Create(bytes, hash) }
     }
 
-    /// Test/host helper: modify a file with UTF-8 text contents.
     pub fn modify(file_id: FileId, text: impl AsRef<str>) -> Self {
         let bytes = text.as_ref().as_bytes().to_vec();
         let hash = hash_once::<FxHasher>(&*bytes);
         Self { file_id, change: Change::Modify(bytes, hash) }
     }
 
-    /// Test/host helper: delete a file.
     pub fn delete(file_id: FileId) -> Self {
         Self { file_id, change: Change::Delete }
     }
@@ -339,7 +297,6 @@ impl Vfs {
                     }
                     // shouldn't occur, but collapse into `Create`
                     (change @ Delete, Modify(new, new_hash)) => {
-                        // Shouldn't occur; collapse into Create like upstream.
                         *change = Create(new, new_hash);
                     }
                     // shouldn't occur, but keep the Create

crates/vfs/src/loader.rs

@@ -1,13 +1,9 @@
-//! Dynamically compatible interface for file watching and reading.
-//!
-//! Owned fork of rust-analyzer `vfs::loader`. SystemVerilog extensions and
-//! exclude prefixes are supplied by callers (`project-model`); glob expansion
-//! happens before `set_config`, not inside the loader.
+//! File loading and watching interface used by the VFS.
 use std::fmt;
 
 use utils::paths::{AbsPath, AbsPathBuf};
 
-/// File extensions loaded from recursive directory entries for SystemVerilog.
+/// Extensions for recursive directory loads (SystemVerilog sources).
 pub const SOURCE_FILE_EXTENSIONS: &[&str] = &["v", "sv", "vh", "svh", "svi", "map"];
 
 /// A set of files on the file system.

crates/vfs/src/notify.rs

@@ -1,15 +1,4 @@
-//! Owned fork of rust-analyzer `vfs-notify`.
-//!
-//! Upstream: <https://github.com/rust-lang/rust-analyzer/tree/master/crates/vfs-notify>
-//!
-//! An implementation of `loader::Handle`, based on `walkdir` and `notify`.
-//!
-//! The file watching bits here are untested and quite probably buggy. For this
-//! reason, by default we don't watch files and rely on editor's file watching
-//! capabilities.
-//!
-//! Hopefully, one day a reliable file watching/walking crate appears on
-//! crates.io, and we can reduce this to trivial glue code.
+//! `loader::Handle` backed by `walkdir` and OS `notify` (best-effort).
 
 use std::{
     fs,

crates/vfs/src/vfs_path.rs

@@ -40,7 +40,6 @@ impl VfsPath {
         }
     }
 
-    /// Alias kept for vide call sites (rust-analyzer name is `as_path`).
     pub fn as_abs_path(&self) -> Option<&AbsPath> {
         self.as_path()
     }

src/global_state/event_loop.rs

@@ -371,8 +371,7 @@ impl GlobalState {
                     return;
                 };
 
-                // Empty loads still flip readiness via Finished Progress, but do not
-                // spam the client with a 0/0 work-done sequence.
+                // Ready already updated; skip empty 0/0 client progress.
                 if progress.n_total == 0 {
                     return;
                 }
@@ -396,8 +395,6 @@ impl GlobalState {
                     }
                 }
             }
-            // rust-analyzer style: content batches have no config_version; only
-            // Progress gates generation readiness.
             vfs_loader::Message::Loaded { files } => {
                 self.process_vfs_files(files, VfsFileSource::ConfigScan);
             }

src/global_state/main_loop.rs

@@ -318,8 +318,6 @@ mod tests {
 
     #[test]
     fn content_batches_apply_without_generation_token() {
-        // rust-analyzer style: Loaded/Changed carry no config_version. Generation
-        // readiness is gated only by Progress; content batches always apply.
         let root = TestDir::new("content-batches-apply");
         let root_path = root.path().to_path_buf();
         let file_path = root_path.join("file.sv");