Adding documentation

src/lib.rs

@@ -1,4 +1,29 @@
 #![forbid(unsafe_code)]
+#![warn(missing_docs)]
+
+//! # Iron Sea - Index SFC DBC
+//!
+//! Index for the Iron Sea toolkit, based on a Space Filling Curve (SFC),
+//! over Dictionary-Based Compression (DBC), which offers great
+//! performances for both range queries over point cloud data and at the
+//! same time uses a storage-efficient index.
+//!
+//! More details in the [paper].
+//!
+//! [paper]: https://infoscience.epfl.ch/record/232536?ln=en
+//!
+//! ## Iron Sea: Database Toolkit
+//! **Iron Sea** provides a set of database engine bricks, which can be
+//! combined and applied on arbitrary data structures.
+//!
+//! Unlike a traditional database, it does not assume a specific
+//! physical structure for the tables nor the records, but relies on the
+//! developer to provide a set of extractor functions which are used by
+//! the specific indices provided.
+//!
+//! This enables the index implementations to be agnostic from the
+//! underlying data structure, and re-used.
+//!
 
 #[macro_use]
 extern crate log;

src/sfc.rs

@@ -53,6 +53,9 @@ struct SFCCell<F> {
     records: Vec<SFCRecord<F>>,
 }
 
+/// Space Filling Curve-based index.
+///
+/// This structure retains the state of the index.
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct SpaceFillingCurve<F, K, V>
 where
@@ -72,6 +75,15 @@ where
     K: Debug + FromIterator<V> + Index<usize, Output = V>,
     V: Clone + Debug + From<usize> + Hash + Ord,
 {
+    /// Creates a new Index from the provided iterator.
+    ///
+    /// * `dimensions`: The number of dimensions of the space, a.k.a the
+    ///                 length of the vector representing a single
+    ///                 position.
+    /// * `cell_bits`: The number of bits to reserve for the grid we
+    ///                build on top of the coordinate dictionaries.
+    ///                We generate 2^`cell_bits` Cells per dimension.
+    ///
     //FIXME: Should accept indexing 0 elements, at least not crash!
     pub fn new<I, R>(iter: I, dimensions: usize, cell_bits: usize) -> Self
     where
@@ -140,6 +152,8 @@ where
         index
     }
 
+    /// Returns a vector of keys which have stored values in the index
+    /// equal to `value`.
     pub fn find_by_value(&self, value: &F) -> Vec<K> {
         let mut results = vec![];
         for cell in &self.index {