From 0d483b3f9bcf59fb6459630b386f31d7cd0f1e8b Mon Sep 17 00:00:00 2001
From: Lionel Sambuc <lionel.sambuc@epfl.ch>
Date: Wed, 18 Mar 2020 15:51:32 +0100
Subject: [PATCH] Adding documentation

---
 src/destructured.rs | 24 +++++++++++++++++++++++-
 src/full_record.rs  | 24 +++++++++++++++++++++++-
 src/lib.rs          | 23 +++++++++++++++++++++++
 3 files changed, 69 insertions(+), 2 deletions(-)

diff --git a/src/destructured.rs b/src/destructured.rs
index d309483..90b7955 100644
--- a/src/destructured.rs
+++ b/src/destructured.rs
@@ -9,6 +9,22 @@ use ironsea_index::RecordFields;
 use serde::Deserialize;
 use serde::Serialize;
 
+/// Implementation of [`ironsea_index`]::[`IndexedDestructured`].
+///
+/// The index is backed by a [`std`]`::`[`collections`]`::`[`HashMap`].
+///
+/// An ordered [`std`]`::`[`vec`]`::`[`Vec`] of keys is maintained, in
+/// order to satisfy range queries.
+///
+/// [`ironsea_index`]: https://epfl-dias.github.io/ironsea_index/ironsea_index/index.html
+/// [`IndexedDestructured`]: https://epfl-dias.github.io/ironsea_index/ironsea_index/trait.IndexedDestructured.html
+///
+/// [`std`]: https://doc.rust-lang.org/std/index.html
+/// [`collections`]: https://doc.rust-lang.org/std/collections/index.html
+/// [`HashMap`]: https://doc.rust-lang.org/std/collections/struct.HashMap.html
+/// [`vec`]: https://doc.rust-lang.org/std/vec/index.html
+/// [`Vec`]: https://doc.rust-lang.org/std/vec/struct.Vec.html
+
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct Index<F, K>
 where
@@ -22,6 +38,7 @@ impl<F, K> Index<F, K>
 where
     K: Clone + Eq + Hash + PartialEq + Ord,
 {
+    /// Creates a new Index from the provided iterator.
     pub fn new<I, R>(iter: I) -> Self
     where
         I: Iterator<Item = R>,
@@ -40,11 +57,16 @@ where
         Index { hashmap, keys }
     }
 
+    /// Return an ordered list of all keys contained in the index.
     pub fn keys(&self) -> &Vec<K> {
         &self.keys
     }
 
-    pub fn index(&self, key: &K) -> usize {
+    /// Returns the position within the index of the key.
+    ///
+    /// If the key is not found, return the index where it should be
+    /// inserted.
+    fn index(&self, key: &K) -> usize {
         match self.keys.binary_search(&key) {
             Ok(i) => i,
             Err(i) => {
diff --git a/src/full_record.rs b/src/full_record.rs
index 60a95a2..37f2287 100644
--- a/src/full_record.rs
+++ b/src/full_record.rs
@@ -9,6 +9,22 @@ use ironsea_index::Record;
 use serde::Deserialize;
 use serde::Serialize;
 
+/// Implementation of [`ironsea_index`]::[`Indexed`].
+///
+/// The index is backed by a [`std`]`::`[`collections`]`::`[`HashMap`].
+///
+/// An ordered [`std`]`::`[`vec`]`::`[`Vec`] of keys is maintained, in
+/// order to satisfy range queries.
+///
+/// [`ironsea_index`]: https://epfl-dias.github.io/ironsea_index/ironsea_index/index.html
+/// [`Indexed`]: https://epfl-dias.github.io/ironsea_index/ironsea_index/trait.Indexed.html
+///
+/// [`std`]: https://doc.rust-lang.org/std/index.html
+/// [`collections`]: https://doc.rust-lang.org/std/collections/index.html
+/// [`HashMap`]: https://doc.rust-lang.org/std/collections/struct.HashMap.html
+/// [`vec`]: https://doc.rust-lang.org/std/vec/index.html
+/// [`Vec`]: https://doc.rust-lang.org/std/vec/struct.Vec.html
+
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct Index<R, K>
 where
@@ -23,6 +39,7 @@ where
     R: Record<K>,
     K: Clone + Eq + Hash + PartialEq + Ord,
 {
+    /// Creates a new Index from the provided iterator.
     pub fn new<I>(iter: I) -> Self
     where
         I: Iterator<Item = R>,
@@ -40,11 +57,16 @@ where
         Index { hashmap, keys }
     }
 
+    /// Return an ordered list of all keys contained in the index.
     pub fn keys(&self) -> &Vec<K> {
         &self.keys
     }
 
-    pub fn index(&self, key: &K) -> usize {
+    /// Returns the position within the index of the key.
+    ///
+    /// If the key is not found, return the index where it should be
+    /// inserted.
+    fn index(&self, key: &K) -> usize {
         match self.keys.binary_search(key) {
             Ok(i) => i,
             Err(i) => {
diff --git a/src/lib.rs b/src/lib.rs
index a4007e5..ff18ca5 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,4 +1,27 @@
 #![forbid(unsafe_code)]
+#![warn(missing_docs)]
+
+//! # Iron Sea - Index Hash Map
+//!
+//! A simple hash map index for the Iron Sea toolkit, based on
+//! [`std`]`::`[`collections`]`::`[`HashMap`].
+//!
+//! [`std`]: https://doc.rust-lang.org/std/index.html
+//! [`collections`]: https://doc.rust-lang.org/std/collections/index.html
+//! [`HashMap`]: https://doc.rust-lang.org/std/collections/struct.HashMap.html
+//!
+//! ## 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.
+//!
 
 mod destructured;
 mod full_record;