diff --git a/src/blake2.rs b/src/blake2.rs index 72054a9..13452a5 100644 --- a/src/blake2.rs +++ b/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::*; diff --git a/src/dag/iter.rs b/src/dag/iter.rs index d0f7272..8748a5f 100644 --- a/src/dag/iter.rs +++ b/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: HashWriter, { dag: &'dag Merkle, - search_nodes: BTreeSet>, + root_nodes: BTreeSet>, } impl<'dag, S, HW> Missing<'dag, S, HW> @@ -33,19 +33,17 @@ where S: Store, HW: HashWriter, { - /// Create an Iterator for the missing nodes given a set of root nodes. - pub fn new(dag: &'dag Merkle, search_nodes: BTreeSet>) -> Self { - Self { dag, search_nodes } + /// Create an iterator for the missing [nodes](Node) given a set of root [nodes](Node). + pub fn new(dag: &'dag Merkle, root_nodes: BTreeSet>) -> Self { + 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>>> { - let nodes = self - .dag - .find_next_non_descendant_nodes(&self.search_nodes)?; - self.search_nodes = BTreeSet::new(); + let nodes = self.dag.find_next_non_descendant_nodes(&self.root_nodes)?; + self.root_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)) diff --git a/src/dag/mod.rs b/src/dag/mod.rs index 286b365..a21a072 100644 --- a/src/dag/mod.rs +++ b/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` -/// trait. +/// of [Nodes](Node) in the dag. /// -/// 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 @@ -63,7 +62,7 @@ where HW: HashWriter, S: Store, { - /// 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>>( &'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 { 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>> { self.nodes.get(id) } - /// Get the set of root node ids. + /// Get the set of root [Node] ids. pub fn get_roots(&self) -> &BTreeSet> { &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 - /// 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 - /// `NodeCompare::Equivalent`. If neither id are parts of the same subgraph then returns - /// `NodeCompare::Uncomparable`. + /// 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::After]. If both id's are equal then the returns + /// [NodeCompare::Equivalent]. If neither id are parts of the same subgraph then returns + /// [NodeCompare::Uncomparable]. pub fn compare(&self, left: &[u8], right: &[u8]) -> Result { 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>, ) -> 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>, diff --git a/src/leveldb/mod.rs b/src/leveldb/mod.rs index e826f97..ee4fd90 100644 --- a/src/leveldb/mod.rs +++ b/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 = std::result::Result; -/// A `Store` implementation using the rusty-leveldb port of leveldb. -/// The Default implementation of this `Default::default()` is an in-memory -/// implementation of the store. +/// A [Store] implementation using the rusty-leveldb port of leveldb. +/// The Default implementation of this is an in-memory implementation +/// of the store. pub struct LevelStore { store: RefCell, } diff --git a/src/node.rs b/src/node.rs index 7dda51b..5519a3c 100644 --- a/src/node.rs +++ b/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 diff --git a/src/rocksdb/mod.rs b/src/rocksdb/mod.rs index 9194977..7b49800 100644 --- a/src/rocksdb/mod.rs +++ b/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 = std::result::Result; +/// A Rocksdb `Store` implementation generic over the single and multithreaded +/// versions. pub struct RocksStore where TM: ThreadMode, @@ -34,13 +36,11 @@ where store: DBWithThreadMode, } -/// Type alias for a `RocksStore`. +/// Type alias for a [RocksStore]. pub type SingleThreadedRocksStore = RocksStore; -/// Type alias for a `RocksStore`. +/// Type alias for a [RocksStore]. pub type MultiThreadedRocksStore = RocksStore; -/// A Rocksdb `Store` implementation generic over the single and multithreaded -/// versions. impl RocksStore where TM: ThreadMode, diff --git a/src/sqlite/mod.rs b/src/sqlite/mod.rs index 306a26a..a68b9fc 100644 --- a/src/sqlite/mod.rs +++ b/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, } diff --git a/src/store.rs b/src/store.rs index 5e89e62..251b8fa 100644 --- a/src/store.rs +++ b/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 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; - /// 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>>; - /// Stores a given node. + /// Stores a given [Node]. fn store(&mut self, node: Node) -> Result<()>; }