From 51d82ced3564aa2f4e49aab6fdeb814652de084a Mon Sep 17 00:00:00 2001
From: Matthias Beyer <mail@beyermatthias.de>
Date: Sun, 4 Apr 2021 16:08:39 +0200
Subject: Add documentation

Signed-off-by: Matthias Beyer <mail@beyermatthias.de>
---
 src/async_dag.rs   | 26 +++++++++++++++++++++-----
 src/dag_backend.rs | 17 +++++++++++++++++
 src/node.rs        |  1 +
 src/node_id.rs     |  1 +
 4 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/src/async_dag.rs b/src/async_dag.rs
index 20a3239..66d79fc 100644
--- a/src/async_dag.rs
+++ b/src/async_dag.rs
@@ -31,6 +31,7 @@ impl<Id, N, Backend> AsyncDag<Id, N, Backend>
           N: Node<Id = Id>,
           Backend: DagBackend<Id, N>
 {
+    /// Create a new DAG with a backend and a HEAD node
     pub async fn new(backend: Backend, head: N) -> Result<Self> {
         backend
             .get(head.id().clone())
@@ -45,6 +46,7 @@ impl<Id, N, Backend> AsyncDag<Id, N, Backend>
             .ok_or_else(|| anyhow!("Head not found in backend"))
     }
 
+    /// Check whether an `id` is in the DAG.
     pub async fn has_id(&self, id: &Id) -> Result<bool> {
         self.stream()
             .map(|r| -> Result<bool> {
@@ -83,6 +85,13 @@ impl<Id, N, Backend> AsyncDag<Id, N, Backend>
             .collect()
     }
 
+    /// Iterate over the DAG
+    ///
+    /// This function returns a Stream over all nodes in the DAG.
+    ///
+    /// # Warning
+    ///
+    /// The order of the nodes is not (yet) guaranteed.
     pub fn stream(&self) -> Stream<Id, N, Backend>  {
         Stream {
             dag: self,
@@ -94,6 +103,11 @@ impl<Id, N, Backend> AsyncDag<Id, N, Backend>
         }
     }
 
+    /// Update the HEAD pointer of the DAG
+    ///
+    /// # Warning
+    ///
+    /// fails if the passed node does not point to the current HEAD in its parents.
     pub async fn update_head(&mut self, node: N) -> Result<Id> {
         if node.parent_ids().iter().any(|id| id == &self.head) {
             self.update_head_unchecked(node).await
@@ -102,6 +116,12 @@ impl<Id, N, Backend> AsyncDag<Id, N, Backend>
         }
     }
 
+    /// Update the HEAD pointer of the DAG, unchecked
+    ///
+    /// # Warning
+    ///
+    /// Does not check whether the passed `node` does point to the current (then old) HEAD in its
+    /// parents. Be careful to not lose nodes from the DAG with this.
     pub async fn update_head_unchecked(&mut self, node: N) -> Result<Id> {
         let id = self.backend.put(node).await?;
         self.head = id.clone();
@@ -143,7 +163,7 @@ pub trait Merger<Id, N>
     fn create_merge_node(&self, left_id: &Id, right_id: &Id) -> Result<N>;
 }
 
-
+/// Stream adapter for streaming all nodes in a DAG
 pub struct Stream<'a, Id, N, Backend>
     where Id: NodeId + Send,
           N: Node<Id = Id>,
@@ -158,12 +178,8 @@ impl<'a, Id, N, Backend> futures::stream::Stream for Stream<'a, Id, N, Backend>
           N: Node<Id = Id>,
           Backend: DagBackend<Id, N>
 {
-
     type Item = Result<N>;
 
-    /// Attempt to resolve the next item in the stream.
-    /// Returns `Poll::Pending` if not ready, `Poll::Ready(Some(x))` if a value
-    /// is ready, and `Poll::Ready(None)` if the stream has completed.
     fn poll_next(mut self: std::pin::Pin<&mut Self>, cx: &mut futures::task::Context<'_>) -> futures::task::Poll<Option<Self::Item>> {
         if let Some(mut fut) = self.as_mut().backlog.pop() {
             match fut.as_mut().poll(cx) {
diff --git a/src/dag_backend.rs b/src/dag_backend.rs
index a91a8ec..62b2cef 100644
--- a/src/dag_backend.rs
+++ b/src/dag_backend.rs
@@ -10,12 +10,29 @@ use async_trait::async_trait;
 use crate::NodeId;
 use crate::Node;
 
+/// An interface to a DAG backend storage
+///
+/// A DAG backend storage is nothing more than a thing that can store (`DagBackend::put`) and load
+/// (`DagBackend::get`) nodes.
 #[async_trait]
 pub trait DagBackend<Id, N>
     where N: Node,
           Id: NodeId + Send
 {
+
+    /// Get a `Node` from the backend that is identified by `id`
+    ///
+    /// # Returns
+    ///
+    /// * Should return Err(_) if the operation failed.
+    /// * Should return Ok(None) if there is no node that is identified by `id`
+    ///
+    /// Otherwise Ok(Some(node)).
     async fn get(&self, id: Id) -> Result<Option<N>>;
+
+    /// Store a `node` in the backend, returning its `Id`
+    ///
+    /// This function should store the `node` in the backend and return the `id` the node has.
     async fn put(&mut self, node: N) -> Result<Id>;
 }
 
diff --git a/src/node.rs b/src/node.rs
index b557928..da57fb8 100644
--- a/src/node.rs
+++ b/src/node.rs
@@ -6,6 +6,7 @@
 
 use crate::NodeId;
 
+/// A Node in the DAG, holding the data.
 pub trait Node {
     type Id: NodeId;
 
diff --git a/src/node_id.rs b/src/node_id.rs
index d849310..0ee7b97 100644
--- a/src/node_id.rs
+++ b/src/node_id.rs
@@ -4,5 +4,6 @@
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 //
 
+/// A unique identifier for a `Node`
 pub trait NodeId: Clone + Eq + PartialEq + std::hash::Hash {
 }
-- 
cgit v1.2.3