From de7880bde987e8a9675c176efcf50f558d23e84a Mon Sep 17 00:00:00 2001
From: Paul Masurel <paul.masurel@gmail.com>
Date: Wed, 21 Sep 2016 10:38:50 +0900
Subject: [PATCH] NOBUG Added comments.

---
 src/core/index.rs        | 12 +++++++++---
 src/lib.rs               | 27 ++++++++++++++++-----------
 src/postings/postings.rs | 21 +++++++++++++--------
 3 files changed, 38 insertions(+), 22 deletions(-)

diff --git a/src/core/index.rs b/src/core/index.rs
index 4f4eb7f3a..d1f34c9d8 100644
--- a/src/core/index.rs
+++ b/src/core/index.rs
@@ -21,6 +21,14 @@ use super::pool::LeasedItem;
 
 const NUM_SEARCHERS: usize = 12; 
 
+/// MetaInformation about the `Index`.
+/// 
+/// This object is serialized on disk in the `meta.json` file.
+/// It keeps information about 
+/// * the searchable segments,
+/// * the index docstamp
+/// * the schema
+///
 #[derive(Clone,Debug,RustcDecodable,RustcEncodable)]
 pub struct IndexMeta {
     segments: Vec<SegmentId>,
@@ -53,7 +61,7 @@ fn load_metas(directory: &Directory) -> Result<IndexMeta> {
     Ok(loaded_meta)
 }
 
-
+/// Tantivy's Search Index
 pub struct Index {
     metas: Arc<RwLock<IndexMeta>>,
     directory: Box<Directory>,
@@ -62,8 +70,6 @@ pub struct Index {
 }
 
 impl Index {
-    
-    
     /// Creates a new index using the `RAMDirectory`.
     ///
     /// The index will be allocated in anonymous memory.
diff --git a/src/lib.rs b/src/lib.rs
index 6f5462ebd..61cbb6a50 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -70,6 +70,9 @@ pub mod schema;
 
 pub use directory::Directory;
 pub use core::searcher::Searcher;
+
+
+/// 
 pub use core::Index;
 pub use indexer::IndexWriter;
 pub use schema::Term;
@@ -95,17 +98,6 @@ pub type Score = f32;
 /// It only makes sense for a given searcher.
 pub type SegmentLocalId = u32;
 
-/// `DocAddress` contains all the necessary information 
-/// to identify a document given a `Searcher` object.
-/// 
-/// It consists in an id identifying its segment, and 
-/// its segment-local `DocId`.
-/// 
-/// The id used for the segment is actually an ordinal
-/// in the list of segment hold by a `Searcher`.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
-pub struct DocAddress(pub SegmentLocalId, pub DocId);
-
 impl DocAddress {
     
     /// Return the segment ordinal.
@@ -140,6 +132,19 @@ impl ScoredDoc {
 }
 
 
+
+/// `DocAddress` contains all the necessary information 
+/// to identify a document given a `Searcher` object.
+/// 
+/// It consists in an id identifying its segment, and 
+/// its segment-local `DocId`.
+/// 
+/// The id used for the segment is actually an ordinal
+/// in the list of segment hold by a `Searcher`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub struct DocAddress(pub SegmentLocalId, pub DocId);
+
+
 #[cfg(test)]
 mod tests {
 
diff --git a/src/postings/postings.rs b/src/postings/postings.rs
index 070c72ca1..e3323ae19 100644
--- a/src/postings/postings.rs
+++ b/src/postings/postings.rs
@@ -4,16 +4,21 @@ use common::HasLen;
 
 
 
-// Postings trait defines all of the information
-// associated with a term.
-// 
-// List of docids, term freqs and positions.
-//
-// It's main implementation is SegmentPostings,
-// but some other implementation mocking SegmentPostings exists,
-// in order to help merging segment or for testing.  
+/// Postings (also called inverted list)
+///
+/// For a given term, it is the list of doc ids of the doc
+/// containing the term. Optionally, for each document,
+/// it may also give access to the term frequency
+/// as well as the list of term positions.
+/// 
+/// Its main implementation is `SegmentPostings`,
+/// but some other implementation mocking SegmentPostings exists,
+/// in order to help merging segment or for testing.  
 pub trait Postings: DocSet {
+    /// Returns the term frequency
     fn term_freq(&self,) -> u32;
+    /// Returns the list of positions of the term, expressed as a list of
+    /// token ordinals.
     fn positions(&self) -> &[u32];
 }