More documenation fixes. Type linking

src/blake2.rs

@@ -11,7 +11,7 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//! Implements the HashWriter interface for the Blake2 hash function.
+//! Implements the [HashWriter] interface for the Blake2 hash function.
 //! Requires the `blake2` feature to be enabled.
 
 use crate::hash::*;

src/dag/iter.rs

@@ -18,14 +18,14 @@ use crate::hash::HashWriter;
 use crate::node::Node;
 use crate::store::{Result, Store};
 
-/// An iterator over the missing nodes in a DAG given a set of root nodes.
+/// An iterator over the missing [nodes](Node) in a [Merkle DAG](Merkle) given a set of root nodes.
 pub struct Missing<'dag, S, HW>
 where
     S: Store<HW>,
     HW: HashWriter,
 {
     dag: &'dag Merkle<S, HW>,
-    search_nodes: BTreeSet<Vec<u8>>,
+    root_nodes: BTreeSet<Vec<u8>>,
 }
 
 impl<'dag, S, HW> Missing<'dag, S, HW>
@@ -33,19 +33,17 @@ where
     S: Store<HW>,
     HW: HashWriter,
 {
-    /// Create an Iterator for the missing nodes given a set of root nodes.
+    /// Create an iterator for the missing [nodes](Node) given a set of root [nodes](Node).
-    pub fn new(dag: &'dag Merkle<S, HW>, search_nodes: BTreeSet<Vec<u8>>) -> Self {
+    pub fn new(dag: &'dag Merkle<S, HW>, root_nodes: BTreeSet<Vec<u8>>) -> Self {
-        Self { dag, search_nodes }
+        Self { dag, root_nodes }
     }
 
-    /// Returns the next set of missing nodes in the iterator.
+    /// Returns the next set of missing [nodes](Node) in the iterator.
     pub fn next(&mut self) -> Result<Option<Vec<Node<HW>>>> {
-        let nodes = self
+        let nodes = self.dag.find_next_non_descendant_nodes(&self.root_nodes)?;
-            .dag
+        self.root_nodes = BTreeSet::new();
-            .find_next_non_descendant_nodes(&self.search_nodes)?;
-        self.search_nodes = BTreeSet::new();
         for id in nodes.iter().map(|n| n.id().to_vec()) {
-            self.search_nodes.insert(id);
+            self.root_nodes.insert(id);
         }
         if nodes.len() > 0 {
             Ok(Some(nodes))

src/dag/mod.rs

@@ -24,7 +24,7 @@ use crate::{
 mod iter;
 pub use iter::*;
 
-/// Node comparison values. In a given Merkle DAG a Node can come `After`, `Before`, be `Equivalent`, or `Uncomparable`.
+/// Node comparison values. In a given Merkle DAG a Node can come [After](NodeCompare::After), [Before](NodeCompare::After), be [Equivalent](NodeCompare::Equivalent), or [Uncomparable](NodeCompare::Uncomparable).
 /// If the two nodes have the same id they are eqivalent. If two nodes are not part of the same sub graph within the DAG
 /// then they are Uncomparable. If one node is an ancestor of another DAG then that node comes before the other. If the
 /// reverse is true then that node comes after the other.
@@ -42,10 +42,9 @@ pub enum NodeCompare {
 /// preserved during construction.
 ///
 /// The merkle dag consists of a set of pointers to the current known roots as well as the total set
-/// of nodes in the dag. Node payload items must be of a single type and implement the `ByteEncoder`
+/// of [Nodes](Node) in the dag.
-/// trait.
 ///
-/// A merkle DAG instance is tied to a specific implementation of the HashWriter interface to ensure
+/// A Merkle instance is tied to a specific implementation of the [HashWriter] interface to ensure
 /// that all hash identifiers are of the same hash algorithm.
 #[derive(Clone, Debug)]
 pub struct Merkle<S, HW>
@@ -63,7 +62,7 @@ where
     HW: HashWriter,
     S: Store<HW>,
 {
-    /// Construct a new empty DAG. The empty DAG is also the default for a DAG.
+    /// Construct a new DAG.
     pub fn new(s: S) -> Self {
         Self {
             nodes: s,
@@ -76,7 +75,7 @@ where
     /// and add it to the DAG with the given payload item and dependency id set. It is idempotent for any
     /// given set of inputs.
     ///
-    /// One result of not constructing and then adding nodes in this way is that we ensure that we always
+    /// One result of not constructing and then adding [nodes](Node) is that we ensure that we always
     /// satisfy the implementation rule in the merkel-crdt's whitepaper.
     pub fn add_node<'a, N: Into<Vec<u8>>>(
         &'a mut self,
@@ -114,31 +113,31 @@ where
         Ok(id.to_vec())
     }
 
-    /// Check if we already have a copy of a node.
+    /// Check if we already have a copy of a [Node].
     pub fn check_for_node(&self, id: &[u8]) -> Result<bool> {
         return self.nodes.contains(id);
     }
 
-    /// Get a node from the DAG by it's hash identifier if it exists.
+    /// Get a [Node] from the DAG by it's hash identifier if it exists.
     pub fn get_node_by_id(&self, id: &[u8]) -> Result<Option<Node<HW>>> {
         self.nodes.get(id)
     }
 
-    /// Get the set of root node ids.
+    /// Get the set of root [Node] ids.
     pub fn get_roots(&self) -> &BTreeSet<Vec<u8>> {
         &self.roots
     }
 
-    /// Get the map of all nodes in the DAG.
+    /// Get the map of all [nodes](Node) in the DAG.
     pub fn get_nodes(&self) -> &S {
         &self.nodes
     }
 
-    /// Compare two nodes by id in the graph. If the left id is an ancestor of the right node
+    /// Compare two [nodes](Node) by id in the graph. If the left id is an ancestor of the right node
-    /// then `returns `NodeCompare::Before`. If the right id is an ancestor of the left node
+    /// then returns [NodeCompare::Before]. If the right id is an ancestor of the left node
-    /// then returns `NodeCompare::After`. If both id's are equal then the returns
+    /// then returns [NodeCompare::After]. If both id's are equal then the returns
-    /// `NodeCompare::Equivalent`. If neither id are parts of the same subgraph then returns
+    /// [NodeCompare::Equivalent]. If neither id are parts of the same subgraph then returns
-    /// `NodeCompare::Uncomparable`.
+    /// [NodeCompare::Uncomparable].
     pub fn compare(&self, left: &[u8], right: &[u8]) -> Result<NodeCompare> {
         Ok(if left == right {
             NodeCompare::Equivalent
@@ -155,7 +154,8 @@ where
         })
     }
 
-    pub fn gap_fill_iter<'dag, 'iter>(
+    /// Construct a [Missing] iterator for this dag given a set of remote root nodes.
+    pub fn missing_iter<'dag, 'iter>(
         &'dag self,
         search_nodes: BTreeSet<Vec<u8>>,
     ) -> Missing<'iter, S, HW>
@@ -165,7 +165,7 @@ where
         Missing::new(self, search_nodes)
     }
 
-    /// Find the immediate next non descendant nodes in this graph for the given `search_nodes`.
+    /// Find the immediate next non descendant [nodes](Node) in this graph for the given `search_nodes`.
     pub fn find_next_non_descendant_nodes(
         &self,
         search_nodes: &BTreeSet<Vec<u8>>,

src/leveldb/mod.rs

@@ -11,7 +11,7 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//! Module implementing a store interface using LevelDB for a MerkleDag.
+//! Module implementing a [Store] interface using LevelDB for a [Merkle Dag](crate::dag::Merkle).
 //! Requires the `rusty-leveldb` feature to be enabled.
 
 use std::cell::RefCell;
@@ -28,9 +28,9 @@ use rusty_leveldb::{self, Options, Status};
 
 pub type Result<T> = std::result::Result<T, Status>;
 
-/// A `Store` implementation using the rusty-leveldb port of leveldb.
+/// A [Store] implementation using the rusty-leveldb port of leveldb.
-/// The Default implementation of this `Default::default()` is an in-memory
+/// The Default implementation of this is an in-memory implementation
-/// implementation of the store.
+/// of the store.
 pub struct LevelStore {
     store: RefCell<rusty_leveldb::DB>,
 }

src/node.rs

@@ -11,7 +11,7 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//! `Node` types for satisfying the properties necessary for a MerkleDag.
+//! [Node] type satisfying the properties necessary for a [Merkle Dag](crate::dag::Merkle).
 
 use std::{collections::BTreeSet, marker::PhantomData};
 
@@ -38,16 +38,16 @@ where
     }
 }
 
-/// A node in a merkle DAG. Nodes are composed of a payload item and a set of dependency_ids.
+/// A node in a [Merkle DAG](crate::dag::Merkle). Nodes are composed of a payload item and a set of dependency_ids.
 /// They provide a unique identifier that is formed from the bytes of the payload as well
 /// as the bytes of the dependency_ids. This is guaranteed to be the id for the same payload
 /// and dependency ids every time making Nodes content-addressable.
 ///
 /// Nodes also expose the unique content address of the item payload alone as a convenience.
 ///
-/// Nodes are tied to a specific implementation of the HashWriter trait which is itself tied
+/// Nodes are tied to a specific implementation of the [HashWriter] trait which is itself tied
 /// to the DAG they are stored in guaranteeing that the same Hashing implementation is used
-/// for each node in the DAG.
+/// for each node in the [Merkle DAG](crate::dag::Merkle).
 #[derive(Debug, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(from = "NodeSerde")]
 pub struct Node<HW>

src/rocksdb/mod.rs

@@ -11,7 +11,7 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//! Module implementing a rocksdb store interfaces for a MerkleDag.
+//! Module implementing a [Store] interface using rocksdb for a [Merkle Dag](crate::dag::Merkle).
 //! Requires the `rocksdb` feature to be enabled.
 
 use std::path::Path;
@@ -27,6 +27,8 @@ use rocksdb::{DBWithThreadMode, MultiThreaded, Options, SingleThreaded, ThreadMo
 
 pub type Result<T> = std::result::Result<T, rocksdb::Error>;
 
+/// A Rocksdb `Store` implementation generic over the single and multithreaded
+/// versions.
 pub struct RocksStore<TM>
 where
     TM: ThreadMode,
@@ -34,13 +36,11 @@ where
     store: DBWithThreadMode<TM>,
 }
 
-/// Type alias for a `RocksStore<SingleThreaded>`.
+/// Type alias for a [RocksStore<SingleThreaded>].
 pub type SingleThreadedRocksStore = RocksStore<SingleThreaded>;
-/// Type alias for a `RocksStore<Multithreaded>`.
+/// Type alias for a [RocksStore<Multithreaded>].
 pub type MultiThreadedRocksStore = RocksStore<MultiThreaded>;
 
-/// A Rocksdb `Store` implementation generic over the single and multithreaded
-/// versions.
 impl<TM> RocksStore<TM>
 where
     TM: ThreadMode,

src/sqlite/mod.rs

@@ -11,6 +11,8 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
+//! Module implementing a [Store] interface using sqlite for a [Merkle Dag](crate::dag::Merkle).
+//! Requires the `sqlite` feature to be enabled.
 use std::path::Path;
 
 use crate::{
@@ -22,6 +24,7 @@ use crate::{
 use ciborium;
 use rusqlite::{self, OptionalExtension};
 
+/// A [Store] implementation using the [rusqlite] bindings for sqlite.
 pub struct SqliteStore {
     conn: rusqlite::Connection,
 }

src/store.rs

@@ -11,7 +11,7 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//! The MerkleDag backing store trait.
+//! The [Merkle Dag](crate::dag::Merkle) backing store trait.
 
 use std::collections::BTreeMap;
 
@@ -25,16 +25,16 @@ pub enum StoreError {
     NoSuchDependents,
 }
 
-/// Trait representing the backing storage interface for a `DAG`.
+/// Trait representing the backing storage interface for a [Merkle DAG](crate::dag::Merkle).
 pub trait Store<HW>
 where
     HW: HashWriter,
 {
-    /// Checks if the `Store` contains a node with this id.
+    /// Checks if the [Store] contains a [Node] with this id.
     fn contains(&self, id: &[u8]) -> Result<bool>;
-    /// Fetches a node from the `Store` by id if it exists.
+    /// Fetches a node from the [Store] by id if it exists.
     fn get(&self, id: &[u8]) -> Result<Option<Node<HW>>>;
-    /// Stores a given node.
+    /// Stores a given [Node].
     fn store(&mut self, node: Node<HW>) -> Result<()>;
 }