From 311ec70d03c27b1b37457ef44510e735fcce0885 Mon Sep 17 00:00:00 2001
From: Arnaud <arnaud.golfouse@free.fr>
Date: Tue, 12 Jan 2021 17:22:57 +0100
Subject: Document vfs public items

---
 crates/vfs/src/file_set.rs | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

(limited to 'crates/vfs/src/file_set.rs')

diff --git a/crates/vfs/src/file_set.rs b/crates/vfs/src/file_set.rs
index 49ca593ac..348b6dbfd 100644
--- a/crates/vfs/src/file_set.rs
+++ b/crates/vfs/src/file_set.rs
@@ -9,6 +9,7 @@ use rustc_hash::FxHashMap;
 
 use crate::{AnchoredPath, FileId, Vfs, VfsPath};
 
+/// A set of [`VfsPath`]s identified by [`FileId`]s.
 #[derive(Default, Clone, Eq, PartialEq)]
 pub struct FileSet {
     files: FxHashMap<VfsPath, FileId>,
@@ -16,9 +17,15 @@ pub struct FileSet {
 }
 
 impl FileSet {
+    /// Returns the number of stored paths.
     pub fn len(&self) -> usize {
         self.files.len()
     }
+
+    /// Get the id of the file corresponding to `path`.
+    ///
+    /// If either `path`'s [`anchor`](AnchoredPath::anchor) or the resolved path is not in
+    /// the set, returns [`None`].
     pub fn resolve_path(&self, path: AnchoredPath<'_>) -> Option<FileId> {
         let mut base = self.paths[&path.anchor].clone();
         base.pop();
@@ -26,19 +33,26 @@ impl FileSet {
         self.files.get(&path).copied()
     }
 
+    /// Get the id corresponding to `path` if it exists in the set.
     pub fn file_for_path(&self, path: &VfsPath) -> Option<&FileId> {
         self.files.get(path)
     }
 
+    /// Get the path corresponding to `file` if it exists in the set.
     pub fn path_for_file(&self, file: &FileId) -> Option<&VfsPath> {
         self.paths.get(file)
     }
 
+    /// Insert the `file_id, path` pair into the set.
+    ///
+    /// # Note
+    /// Multiple [`FileId`] can be mapped to the same [`VfsPath`], and vice-versa.
     pub fn insert(&mut self, file_id: FileId, path: VfsPath) {
         self.files.insert(path.clone(), file_id);
         self.paths.insert(file_id, path);
     }
 
+    /// Iterate over this set's ids.
     pub fn iter(&self) -> impl Iterator<Item = FileId> + '_ {
         self.paths.keys().copied()
     }
@@ -50,6 +64,23 @@ impl fmt::Debug for FileSet {
     }
 }
 
+/// This contains path prefixes to partition a [`Vfs`] into [`FileSet`]s.
+///
+/// # Example
+/// ```rust
+/// # use vfs::{file_set::FileSetConfigBuilder, VfsPath, Vfs};
+/// let mut builder = FileSetConfigBuilder::default();
+/// builder.add_file_set(vec![VfsPath::new_virtual_path("/src".to_string())]);
+/// let config = builder.build();
+/// let mut file_system = Vfs::default();
+/// file_system.set_file_contents(VfsPath::new_virtual_path("/src/main.rs".to_string()), Some(vec![]));
+/// file_system.set_file_contents(VfsPath::new_virtual_path("/src/lib.rs".to_string()), Some(vec![]));
+/// file_system.set_file_contents(VfsPath::new_virtual_path("/build.rs".to_string()), Some(vec![]));
+/// // contains the sets :
+/// // { "/src/main.rs", "/src/lib.rs" }
+/// // { "build.rs" }
+/// let sets = config.partition(&file_system);
+/// ```
 #[derive(Debug)]
 pub struct FileSetConfig {
     n_file_sets: usize,
@@ -63,9 +94,14 @@ impl Default for FileSetConfig {
 }
 
 impl FileSetConfig {
+    /// Returns a builder for `FileSetConfig`.
     pub fn builder() -> FileSetConfigBuilder {
         FileSetConfigBuilder::default()
     }
+
+    /// Partition `vfs` into `FileSet`s.
+    ///
+    /// Creates a new [`FileSet`] for every set of prefixes in `self`.
     pub fn partition(&self, vfs: &Vfs) -> Vec<FileSet> {
         let mut scratch_space = Vec::new();
         let mut res = vec![FileSet::default(); self.len()];
@@ -91,6 +127,7 @@ impl FileSetConfig {
     }
 }
 
+/// Builder for [`FileSetConfig`].
 pub struct FileSetConfigBuilder {
     roots: Vec<Vec<VfsPath>>,
 }
@@ -102,12 +139,17 @@ impl Default for FileSetConfigBuilder {
 }
 
 impl FileSetConfigBuilder {
+    /// Returns the number of sets currently held.
     pub fn len(&self) -> usize {
         self.roots.len()
     }
+
+    /// Add a new set of paths prefixes.
     pub fn add_file_set(&mut self, roots: Vec<VfsPath>) {
         self.roots.push(roots)
     }
+
+    /// Build the `FileSetConfig`.
     pub fn build(self) -> FileSetConfig {
         let n_file_sets = self.roots.len() + 1;
         let map = {
-- 
cgit v1.2.3