From 2c9979debc8c4f6574ac5667c76c6a71c6c99fba Mon Sep 17 00:00:00 2001
From: austinabell <austinabell8@gmail.com>
Date: Tue, 9 Feb 2021 12:14:42 -0500
Subject: [PATCH] Update ipld docs

---
 ipld/blockstore/src/lib.rs      | 3 +++
 ipld/blockstore/src/resolve.rs  | 4 ++--
 ipld/blockstore/src/tracking.rs | 2 ++
 ipld/cid/src/lib.rs             | 7 +++++++
 ipld/hamt/src/hash_algorithm.rs | 3 +++
 5 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/ipld/blockstore/src/lib.rs b/ipld/blockstore/src/lib.rs
index 14c05796159a..a9667dd41b28 100644
--- a/ipld/blockstore/src/lib.rs
+++ b/ipld/blockstore/src/lib.rs
@@ -4,6 +4,9 @@
 #[cfg(feature = "buffered")]
 mod buffered;
 #[cfg(feature = "resolve")]
+/// This module is used for resolving Cids and Ipld recursively. This is generally only needed
+/// for testing because links should generally not be collapsed to generate a singular data
+/// structure, or this would lead to ambiguity of the data.
 pub mod resolve;
 #[cfg(feature = "sled")]
 mod sled;
diff --git a/ipld/blockstore/src/resolve.rs b/ipld/blockstore/src/resolve.rs
index 17e85da2b6a8..1194cb31cce0 100644
--- a/ipld/blockstore/src/resolve.rs
+++ b/ipld/blockstore/src/resolve.rs
@@ -6,7 +6,7 @@ use cid::{Cid, DAG_CBOR};
 use forest_ipld::Ipld;
 use std::error::Error as StdError;
 
-/// Resolves link to recursively resolved Ipld with no hash links.
+/// Resolves link to recursively resolved [Ipld] with no hash links.
 pub fn resolve_cids_recursive<BS>(
     bs: &BS,
     cid: &Cid,
@@ -22,7 +22,7 @@ where
     Ok(ipld)
 }
 
-/// Resolves Ipld links recursively, building an Ipld structure with no hash links.
+/// Resolves [Ipld] links recursively, building an [Ipld] structure with no hash links.
 pub fn resolve_ipld<BS>(
     bs: &BS,
     ipld: &mut Ipld,
diff --git a/ipld/blockstore/src/tracking.rs b/ipld/blockstore/src/tracking.rs
index 08e2fb5a51bf..663aa08fd5b1 100644
--- a/ipld/blockstore/src/tracking.rs
+++ b/ipld/blockstore/src/tracking.rs
@@ -9,6 +9,8 @@ use db::{Error, Store};
 use std::cell::RefCell;
 use std::error::Error as StdError;
 
+/// Stats for a [TrackingBlockStore] this indicates the amount of read and written data
+/// to the wrapped store.
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct BSStats {
     /// Number of reads
diff --git a/ipld/cid/src/lib.rs b/ipld/cid/src/lib.rs
index 8721a6d8a61b..6773b2be2b82 100644
--- a/ipld/cid/src/lib.rs
+++ b/ipld/cid/src/lib.rs
@@ -29,9 +29,13 @@ const MULTIBASE_IDENTITY: u8 = 0;
 #[cfg(feature = "json")]
 pub mod json;
 
+/// Cbor [Cid] codec.
 pub const DAG_CBOR: u64 = 0x71;
+/// Sealed commitment [Cid] codec.
 pub const FIL_COMMITMENT_SEALED: u64 = 0xf102;
+/// Unsealed commitment [Cid] codec.
 pub const FIL_COMMITMENT_UNSEALED: u64 = 0xf101;
+/// Raw [Cid] codec. This represents data that is not encoded using any protocol.
 pub const RAW: u64 = 0x55;
 
 /// Constructs a cid with bytes using default version and codec
@@ -46,6 +50,9 @@ pub fn new_from_prefix(prefix: &Prefix, data: &[u8]) -> Result<Cid, Error> {
     Cid::new(prefix.version, prefix.codec, hash)
 }
 
+/// Content identifier for any Ipld data. This Cid consists of a version, a codec (or serialization)
+/// protocol and a multihash (hash of the Ipld data). Cids allow for hash linking, where the Cids
+/// are used to resolve any arbitrary data over a network or from local storage.
 #[derive(PartialEq, Eq, Clone, Copy, Default, Hash, PartialOrd, Ord)]
 pub struct Cid(CidGeneric<multihash::U32>);
 
diff --git a/ipld/hamt/src/hash_algorithm.rs b/ipld/hamt/src/hash_algorithm.rs
index 63c0103146ad..880cac7bfd8a 100644
--- a/ipld/hamt/src/hash_algorithm.rs
+++ b/ipld/hamt/src/hash_algorithm.rs
@@ -27,6 +27,7 @@ impl Hasher for Sha2HasherWrapper {
     }
 }
 
+/// Sha256 hashing algorithm used for hashing keys in the Hamt.
 #[derive(Debug)]
 pub enum Sha256 {}
 
@@ -60,6 +61,8 @@ impl Hasher for IdentityHasher {
     }
 }
 
+/// Identity hashing algorithm used for hashing keys in the Hamt. This should only be used
+/// for testing. The hash is just the first 32 bytes of the serialized key.
 #[cfg(feature = "identity")]
 #[derive(Debug)]
 pub enum Identity {}