docs: deny missing docs (#1156)

* docs: deny missing docs

* docs: add docs for the two variants of iroh_io::Either

(this thing is on the way out anyway, but for now let's just document it...)

* docs: comment iroh-bytes

* comment out deny(missing_docs) for iroh-metrics

* docs: document non default iroh-io features

* refactor: reduce surface area

---------

Co-authored-by: Ruediger Klaehn <rklaehn@protonmail.com>

iroh-bytes/src/cid.rs

@@ -1,7 +1,14 @@
+//! A newtype wrapper for a blake3 hash that has a Display and FromStr
+//! implementation that conforms to the [cid](/~https://github.com/multiformats/cid) spec.
 use std::{fmt, str::FromStr};
 
 use crate::util::Hash;
 
+/// A newtype wrapper for a blake3 hash that has a Display and FromStr
+/// implementation that conforms to the [cid](/~https://github.com/multiformats/cid) spec.
+///
+/// Note that this is not a full cid implementation, it only supports the blake3 hash
+/// function and the raw codec.
 #[repr(transparent)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct Blake3Cid(pub Hash);
@@ -14,14 +21,17 @@ const CID_PREFIX: [u8; 4] = [
 ];
 
 impl Blake3Cid {
+    /// Wrap a hash as a cid.
     pub fn new(hash: Hash) -> Self {
         Blake3Cid(hash)
     }
 
+    /// Get the hash from the cid.
     pub fn as_hash(&self) -> &Hash {
         &self.0
     }
 
+    /// Get the cid as bytes.
     pub fn as_bytes(&self) -> [u8; 36] {
         let hash = self.0.as_bytes();
         let mut res = [0u8; 36];
@@ -30,6 +40,13 @@ impl Blake3Cid {
         res
     }
 
+    /// Try to create a blake3 cid from cid bytes.
+    ///
+    /// This will only work if the prefix is the following:
+    /// - version 1
+    /// - raw codec
+    /// - blake3 hash function
+    /// - 32 byte hash size
     pub fn from_bytes(bytes: &[u8]) -> anyhow::Result<Self> {
         anyhow::ensure!(
             bytes.len() == 36,

iroh-bytes/src/lib.rs

@@ -1,7 +1,7 @@
 //! Send data over the internet.
-// #![deny(missing_docs)] TODO: fix me before merging
+
+#![deny(missing_docs, rustdoc::broken_intra_doc_links)]
 #![recursion_limit = "256"]
-#![deny(rustdoc::broken_intra_doc_links)]
 
 pub mod blobs;
 pub mod cid;

iroh-bytes/src/protocol.rs

@@ -34,6 +34,7 @@ pub struct RequestToken {
 }
 
 impl RequestToken {
+    /// Creates a new request token from bytes.
     pub fn new(bytes: impl Into<Bytes>) -> Result<Self> {
         let bytes: Bytes = bytes.into();
         ensure!(
@@ -107,7 +108,9 @@ impl Request {
 /// Custom request handlers will receive this struct destructured into
 /// handler arguments
 pub struct CustomGetRequest {
+    /// The optional request token
     pub token: Option<RequestToken>,
+    /// The opaque request data
     pub data: Bytes,
 }
 
@@ -157,10 +160,12 @@ impl GetRequest {
         }
     }
 
+    /// Set the request token
     pub fn with_token(self, token: Option<RequestToken>) -> Self {
         Self { token, ..self }
     }
 
+    /// Get the request token
     pub fn token(&self) -> Option<&RequestToken> {
         self.token.as_ref()
     }
@@ -252,11 +257,12 @@ pub enum Closed {
 }
 
 impl Closed {
+    /// The close reason as bytes. This is a valid utf8 string describing the reason.
     pub fn reason(&self) -> &'static [u8] {
         match self {
-            Closed::StreamDropped => &b"stream dropped"[..],
-            Closed::ProviderTerminating => &b"provider terminating"[..],
-            Closed::RequestReceived => &b"request received"[..],
+            Closed::StreamDropped => b"stream dropped",
+            Closed::ProviderTerminating => b"provider terminating",
+            Closed::RequestReceived => b"request received",
         }
     }
 }

iroh-bytes/src/provider.rs

@@ -112,18 +112,35 @@ pub enum Event {
 #[derive(Debug, Serialize, Deserialize)]
 pub enum ValidateProgress {
     /// started validating
-    Starting { total: u64 },
+    Starting {
+        /// The total number of entries to validate
+        total: u64,
+    },
     /// We started validating an entry
     Entry {
+        /// a new unique id for this entry
         id: u64,
+        /// the hash of the entry
         hash: Hash,
+        /// the path of the entry on the local file system
         path: Option<PathBuf>,
+        /// the size of the entry
         size: u64,
     },
     /// We got progress ingesting item `id`
-    Progress { id: u64, offset: u64 },
+    Progress {
+        /// the unique id of the entry
+        id: u64,
+        /// the offset of the progress, in bytes
+        offset: u64,
+    },
     /// We are done with `id`
-    Done { id: u64, error: Option<String> },
+    Done {
+        /// the unique id of the entry
+        id: u64,
+        /// an error if we failed to validate the entry
+        error: Option<String>,
+    },
     /// We are done with the whole operation
     AllDone,
     /// We got an error and need to abort
@@ -134,14 +151,36 @@ pub enum ValidateProgress {
 #[derive(Debug, Serialize, Deserialize)]
 pub enum ProvideProgress {
     /// An item was found with name `name`, from now on referred to via `id`
-    Found { name: String, id: u64, size: u64 },
+    Found {
+        /// a new unique id for this entry
+        id: u64,
+        /// the name of the entry
+        name: String,
+        /// the size of the entry in bytes
+        size: u64,
+    },
     /// We got progress ingesting item `id`
-    Progress { id: u64, offset: u64 },
+    Progress {
+        /// the unique id of the entry
+        id: u64,
+        /// the offset of the progress, in bytes
+        offset: u64,
+    },
     /// We are done with `id`, and the hash is `hash`
-    Done { id: u64, hash: Hash },
+    Done {
+        /// the unique id of the entry
+        id: u64,
+        /// the hash of the entry
+        hash: Hash,
+    },
     /// We are done with the whole operation
-    AllDone { hash: Hash },
-    /// We got an error and need to abort
+    AllDone {
+        /// the hash of the created collection
+        hash: Hash,
+    },
+    /// We got an error and need to abort.
+    ///
+    /// This will be the last message in the stream.
     Abort(RpcError),
 }
 
@@ -236,17 +275,20 @@ pub enum DbEntry {
 }
 
 impl DbEntry {
+    /// True if this is an entry that is stored externally.
     pub fn is_external(&self) -> bool {
         matches!(self, DbEntry::External { .. })
     }
 
+    /// Path to the external data, or `None` if this is an internal entry.
     pub fn blob_path(&self) -> Option<&Path> {
         match self {
             DbEntry::External { path, .. } => Some(path),
             DbEntry::Internal { .. } => None,
         }
     }
 
+    /// Get the outboard data for this entry, as a `Bytes`.
     pub fn outboard_reader(&self) -> impl Future<Output = io::Result<Bytes>> + 'static {
         futures::future::ok(match self {
             DbEntry::External { outboard, .. } => outboard.clone(),
@@ -413,10 +455,15 @@ pub async fn transfer_collection<D: BaoMap, E: EventSender>(
     Ok(SentStatus::Sent)
 }
 
+/// Trait for sending events.
 pub trait EventSender: Clone + Send + 'static {
+    /// Send an event.
+    ///
+    /// Returns `None` if the event was sent successfully, or `Some(event)` if the event could not be sent.
     fn send(&self, event: Event) -> Option<Event>;
 }
 
+/// Handle a single connection.
 pub async fn handle_connection<
     D: BaoMap,
     C: CustomGetHandler<D>,
@@ -536,6 +583,7 @@ async fn handle_custom_get<E: EventSender, D: BaoMap>(
     handle_get(db, request, writer).await
 }
 
+/// Handle a single standard get request.
 pub async fn handle_get<D: BaoMap, E: EventSender>(
     db: D,
     request: GetRequest,
@@ -620,12 +668,16 @@ impl<E: EventSender> ResponseWriter<E> {
     }
 }
 
+/// Status  of a send operation
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum SentStatus {
+    /// The requested data was sent
     Sent,
+    /// The requested data was not found
     NotFound,
 }
 
+/// Send a
 pub async fn send_blob<D: BaoMap, W: AsyncWrite + Unpin + Send + 'static>(
     db: &D,
     name: Hash,
@@ -656,6 +708,7 @@ pub async fn send_blob<D: BaoMap, W: AsyncWrite + Unpin + Send + 'static>(
     }
 }
 
+/// Data for a blob
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct BlobData {
     /// Outboard data from bao.

iroh-bytes/src/provider/database.rs

@@ -1,3 +1,7 @@
+//! The database used by the iroh node.
+//!
+//! Databases are key value stores that store data and associated outboard data
+//! for blake3 hashes, in addition to some metadata.
 use super::DbEntry;
 use crate::{
     provider::ValidateProgress,
@@ -11,7 +15,7 @@ use futures::{
     future::{self, BoxFuture, Either},
     FutureExt, StreamExt,
 };
-use iroh_io::{AsyncSliceReader, AsyncSliceReaderExt, FileAdapter};
+use iroh_io::{AsyncSliceReader, FileAdapter};
 use std::{
     collections::{BTreeMap, BTreeSet, HashMap},
     fmt, io,
@@ -36,10 +40,16 @@ pub const FNAME_PATHS: &str = "paths.bin";
 #[derive(Debug, Clone, Default)]
 pub struct Database(Arc<RwLock<HashMap<Hash, DbEntry>>>);
 
+/// An in memory implementation of [BaoMap] and [BaoReadonlyDb], useful for
+/// testing and short lived nodes.
 #[derive(Debug, Clone, Default)]
 pub struct InMemDatabase(Arc<HashMap<Hash, (PreOrderMemOutboard, Bytes)>>);
 
 impl InMemDatabase {
+    /// Create a new [InMemDatabase] from a sequence of entries.
+    ///
+    /// Returns the database and a map of names to computed blake3 hashes.
+    /// In case of duplicate names, the last entry is used.
     pub fn new(
         entries: impl IntoIterator<Item = (impl Into<String>, impl AsRef<[u8]>)>,
     ) -> (Self, BTreeMap<String, blake3::Hash>) {
@@ -62,6 +72,7 @@ impl InMemDatabase {
         (Self(Arc::new(res)), names)
     }
 
+    /// Insert a new entry into the database, and return the hash of the entry.
     pub fn insert(&mut self, data: impl AsRef<[u8]>) -> Hash {
         let inner = Arc::make_mut(&mut self.0);
         let data: &[u8] = data.as_ref();
@@ -76,12 +87,14 @@ impl InMemDatabase {
         hash
     }
 
+    /// Get the bytes associated with a hash, if they exist.
     pub fn get(&self, hash: &Hash) -> Option<Bytes> {
         let entry = self.0.get(hash)?;
         Some(entry.1.clone())
     }
 }
 
+/// The [BaoMapEntry] implementation for [InMemDatabase].
 #[derive(Debug, Clone)]
 pub struct InMemDatabaseEntry {
     outboard: PreOrderMemOutboard<Bytes>,
@@ -140,11 +153,15 @@ impl BaoReadonlyDb for InMemDatabase {
 /// create the readers must be `Send`, but the readers themselves don't have to
 /// be.
 pub trait BaoMapEntry<D: BaoMap>: Clone + Send + Sync + 'static {
+    /// The hash of the entry
     fn hash(&self) -> blake3::Hash;
+    /// A future that resolves to a reader that can be used to read the outboard
     fn outboard(&self) -> BoxFuture<'_, io::Result<D::Outboard>>;
+    /// A future that resolves to a reader that can be used to read the data
     fn data_reader(&self) -> BoxFuture<'_, io::Result<D::DataReader>>;
 }
 
+/// The [BaoMapEntry] implementation for [Database].
 #[derive(Debug, Clone)]
 pub struct DbPair {
     hash: blake3::Hash,
@@ -158,8 +175,7 @@ impl BaoMapEntry<Database> for DbPair {
 
     fn outboard(&self) -> BoxFuture<'_, io::Result<PreOrderMemOutboard>> {
         async move {
-            let mut reader = self.entry.outboard_reader().await?;
-            let bytes = reader.read_to_end().await?;
+            let bytes = self.entry.outboard_reader().await?;
             let hash = self.hash;
             PreOrderMemOutboard::new(hash, IROH_BLOCK_SIZE, bytes)
         }
@@ -615,10 +631,12 @@ impl Database {
         }
     }
 
+    /// Get the entry for a given hash.
     pub fn get(&self, key: &Hash) -> Option<DbEntry> {
         self.0.read().unwrap().get(key).cloned()
     }
 
+    /// Compute the union of this database with another.
     pub fn union_with(&self, db: HashMap<Hash, DbEntry>) {
         let mut inner = self.0.write().unwrap();
         for (k, v) in db {

iroh-bytes/src/provider/ticket.rs

@@ -34,6 +34,7 @@ pub struct Ticket {
 }
 
 impl Ticket {
+    /// Creates a new ticket.
     pub fn new(
         hash: Hash,
         peer: PeerId,
@@ -94,6 +95,7 @@ impl Ticket {
         (hash, peer, addrs, token)
     }
 
+    /// Convert this ticket into a [`get::Options`], adding the given keypair.
     pub fn as_get_options(&self, keypair: Keypair, derp_map: Option<DerpMap>) -> get::Options {
         get::Options {
             peer_id: self.peer,

iroh-bytes/src/runtime.rs

@@ -2,6 +2,7 @@
 //! tokio runtime and a set of single threaded runtimes.
 use std::sync::Arc;
 
+/// A handle to the iroh runtime
 #[derive(Debug, Clone)]
 pub struct Handle {
     inner: Arc<HandleInner>,
@@ -27,10 +28,12 @@ impl Handle {
         ))
     }
 
+    /// Get a handle to the main tokio runtime
     pub fn main(&self) -> &tokio::runtime::Handle {
         &self.inner.rt
     }
 
+    /// Get a handle to the thread pool for single threaded executors
     pub fn local_pool(&self) -> &tokio_util::task::LocalPoolHandle {
         &self.inner.tpc
     }