From ebca90476786062cc0bb3030bcf2c301ee1568a7 Mon Sep 17 00:00:00 2001
From: Paul Masurel <paul.masurel@gmail.com>
Date: Tue, 7 Mar 2017 09:58:51 +0900
Subject: [PATCH] NOBUG added rustdoc

---
 src/core/segment_meta.rs           |  8 +++++++-
 src/directory/managed_directory.rs | 31 ++++++++++++++++++++++++++++++
 src/indexer/segment_manager.rs     |  4 ++--
 src/indexer/segment_updater.rs     |  2 +-
 4 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/src/core/segment_meta.rs b/src/core/segment_meta.rs
index 387617f39..a12428b07 100644
--- a/src/core/segment_meta.rs
+++ b/src/core/segment_meta.rs
@@ -45,7 +45,13 @@ impl SegmentMeta {
             .unwrap_or(0u32)
     }
 
-    pub fn living_files(&self) -> HashSet<PathBuf> {
+    /// Returns the list of files that
+    /// are required for the segment meta.
+    ///
+    /// This is useful as the way tantivy removes files
+    /// is by removing all files that have been created by tantivy
+    /// and are not used by any segment anymore.
+    pub fn list_files(&self) -> HashSet<PathBuf> {
         SegmentComponent::iterator()
             .map(|component| {
                 self.relative_path(*component)
diff --git a/src/directory/managed_directory.rs b/src/directory/managed_directory.rs
index 2dc540229..3eefcf996 100644
--- a/src/directory/managed_directory.rs
+++ b/src/directory/managed_directory.rs
@@ -12,6 +12,15 @@ use core::MANAGED_FILEPATH;
 use Result;
 use Error;
 
+/// Wrapper of directories that keeps track of files created by Tantivy.
+///
+/// A managed directory is just a wrapper of a directory
+/// that keeps a (persisted) list of the files that 
+/// have been created (and not deleted) by tantivy so far.
+///
+/// Thanks to this list, it implements a `garbage_collect` method
+/// that removes the files that were created by tantivy and are not
+/// useful anymore.
 #[derive(Debug)]
 pub struct ManagedDirectory {
     directory: Box<Directory>,
@@ -19,6 +28,8 @@ pub struct ManagedDirectory {
 }
 
 impl ManagedDirectory {
+
+    /// Wraps a directory as managed directory.
     pub fn new<Dir: Directory>(directory: Dir) -> Result<ManagedDirectory> {
         match directory.atomic_read(&MANAGED_FILEPATH) {
             Ok(data) => {
@@ -42,6 +53,17 @@ impl ManagedDirectory {
         }
     }
 
+    /// Garbage collect unused files.
+    ///
+    /// Removes the files that were created by `tantivy` and are not
+    /// used by any segment anymore.
+    /// 
+    /// * `living_files` - List of files that are still used by the index.
+    ///
+    /// This method does not panick nor returns errors.
+    /// If a file cannot be deleted (for permission reasons for instance)
+    /// an error is simply logged, and the file remains in the list of managed
+    /// files.
     pub fn garbage_collect(&mut self, living_files: HashSet<PathBuf>) {
         let mut managed_has_changed: bool = false;
         {
@@ -80,6 +102,8 @@ impl ManagedDirectory {
         }
     }
 
+    /// Saves the file containing the list of existing files
+    /// that were created by tantivy.
     fn save_managed_paths(&mut self,) -> io::Result<()> {
         let managed_files_lock = self.managed_paths
             .read()
@@ -90,6 +114,13 @@ impl ManagedDirectory {
         Ok(())
     }
 
+    /// Registers a file as managed
+    /// 
+    /// This method must be called before the file is 
+    /// actually created to ensure that a failure between
+    /// registering the filepath and creating the file
+    /// will not lead to garbage files that will 
+    /// never get removed.
     fn register_file_as_managed(&mut self, filepath: &Path) -> io::Result<()> {
         let has_changed = {
             let mut managed_files_lock = self
diff --git a/src/indexer/segment_manager.rs b/src/indexer/segment_manager.rs
index 5ba5dd220..ad35702ef 100644
--- a/src/indexer/segment_manager.rs
+++ b/src/indexer/segment_manager.rs
@@ -71,7 +71,7 @@ impl SegmentManager {
         segment_entries
     }
 
-    pub fn living_files(&self) -> HashSet<PathBuf> {
+    pub fn list_files(&self) -> HashSet<PathBuf> {
         let registers_lock = self.read();
         let mut files = HashSet::new();
         files.insert(META_FILEPATH.clone());
@@ -89,7 +89,7 @@ impl SegmentManager {
                     .map(SegmentMeta::new));
         
         for segment_meta in segment_metas {
-            files.extend(segment_meta.living_files());
+            files.extend(segment_meta.list_files());
         }
         files
     }
diff --git a/src/indexer/segment_updater.rs b/src/indexer/segment_updater.rs
index 347212c83..663e36609 100644
--- a/src/indexer/segment_updater.rs
+++ b/src/indexer/segment_updater.rs
@@ -194,7 +194,7 @@ impl SegmentUpdater {
                     opstamp,
                     directory.box_clone().borrow_mut()).expect("Could not save metas.");
             }
-            let living_files = segment_updater.0.segment_manager.living_files();
+            let living_files = segment_updater.0.segment_manager.list_files();
             index.directory_mut().garbage_collect(living_files);
             segment_updater.consider_merge_options();