chore: Add doc requirement to CI, add missing docs

Signed-off-by: Mikołaj Florkiewicz <[email protected]>

.github/workflows/ci.yml

@@ -12,8 +12,16 @@ jobs:
     steps:
     - uses: actions/checkout@v1
     - name: Run clippy
-      run: cargo clippy --all --all-targets -- -D warnings
+      run: cargo clippy --all --all-targets -- -D warnings -D missing-docs
 
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v1
+    - name: Run rustdoc check
+      env:
+        RUSTDOCFLAGS: -D warnings
+      run: cargo doc
 
   fmt:
     runs-on: ubuntu-latest

examples/client.rs → examples/node.rs

@@ -1,3 +1,26 @@
+//! Example bitswap node implementation allowing with basic interaction over cli
+//!
+//! It shows off example way to setup beetswap behaviour with a libp2p swarm and then either
+//! connecting to another node and/or listening for incoming connections. In both cases both
+//! the server and the client parts of the bitswap are running.
+//!
+//! Example invocations:
+//!
+//! Listen on port `9898` and serve single block with contents "12345"
+//! ```sh
+//! cargo run --example=node -- -l 9898 --preload-blockstore-string 12345
+//! ```
+//!
+//! Connect to `10.0.0.101` on port `9898` and ask for CID `bafkreic...` (it's a CID of "12345" string above). You can specify multiple CIDs at once.
+//! ```sh
+//! cargo run --example=node  -- -p /ip4/10.0.0.101/tcp/9898 bafkreiczsrdrvoybcevpzqmblh3my5fu6ui3tgag3jm3hsxvvhaxhswpyu
+//! ```
+//!
+//! Listen on port `9898` and requests provided CID from them until it gets correct response with
+//! data
+//! ```sh
+//! cargo run --example=node  -- -l 9898 bafkreiczsrdrvoybcevpzqmblh3my5fu6ui3tgag3jm3hsxvvhaxhswpyu
+//! ```
 use std::collections::HashMap;
 use std::time::Duration;
 

src/lib.rs

@@ -1,3 +1,6 @@
+#![cfg_attr(docs_rs, feature(doc_cfg))]
+#![doc = include_str!("../README.md")]
+
 use std::sync::{Arc, Mutex};
 use std::task::{Context, Poll};
 
@@ -52,19 +55,35 @@ where
 /// Event produced by [`Behaviour`].
 #[derive(Debug)]
 pub enum Event {
-    GetQueryResponse { query_id: QueryId, data: Vec<u8> },
-    GetQueryError { query_id: QueryId, error: Error },
+    /// Requested block has been successfuly retrieved
+    GetQueryResponse {
+        /// Id of the query, returned by [`Behaviour::get`]
+        query_id: QueryId,
+        /// Data of the requested block
+        data: Vec<u8>,
+    },
+    /// Error occurred while fetching block
+    GetQueryError {
+        /// Id of the query, returned by [`Behaviour::get`]
+        query_id: QueryId,
+        /// Error that occurred when getting the data
+        error: Error,
+    },
 }
 
 /// Representation of all the errors that can occur when interacting with this crate.
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
+    /// Encountered CID with multihash longer than max set when creating the [`Behaviour`]
     #[error("Invalid multihash size")]
     InvalidMultihashSize,
 
+    /// Invalid protocol prefix provided when building `Behaviour`, see
+    /// [`BehaviourBuilder::protocol_prefix`]
     #[error("Invalid protocol prefix: {0}")]
     InvalidProtocolPrefix(String),
 
+    /// Error received when interacting with blockstore
     #[error("Blockstore error: {0}")]
     Blockstore(#[from] BlockstoreError),
 }
@@ -212,6 +231,7 @@ pub enum ToHandlerEvent {
     QueueOutgoingMessages(Vec<(Vec<u8>, Vec<u8>)>),
 }
 
+#[doc(hidden)]
 pub enum StreamRequester {
     Client,
     Server,

src/message.rs

@@ -13,9 +13,6 @@ pub(crate) const MAX_MESSAGE_SIZE: usize = 4 * 1024 * 1024;
 
 pub(crate) struct Codec;
 
-#[derive(Debug, thiserror::Error)]
-pub(crate) enum CodecError {}
-
 impl Encoder for Codec {
     type Item<'a> = &'a Message;
     type Error = io::Error;

src/multihasher.rs

@@ -1,3 +1,13 @@
+//! Module responsible for calculating hashes for data received
+//!
+//! For interoperability `StandardMultihasher` is registered by default, which uses hashes
+//! provided by [`multihash_codetable::Code`]. If you need to register your own multihashes,
+//! you can implement [`Multihasher`] trait and then register the struct with
+//! [`BehaviourBuilder::register_multihasher`] when creating the behaviour.
+//!
+//! [`BehaviourBuilder::register_multihasher`]:
+//! crate::builder::BehaviourBuilder::register_multihasher
+
 use std::collections::VecDeque;
 use std::fmt::{self, Display};
 
@@ -40,10 +50,13 @@ pub enum MultihasherError {
 }
 
 impl MultihasherError {
+    /// Custom error, causes block to be ignored
     pub fn custom(e: impl Display) -> MultihasherError {
         MultihasherError::Custom(e.to_string())
     }
 
+    /// Custom fatal error, causes block to be ignored and stream from which it was received to
+    /// close
     pub fn custom_fatal(e: impl Display) -> MultihasherError {
         MultihasherError::CustomFatal(e.to_string())
     }

src/utils.rs

@@ -1,3 +1,5 @@
+//! Helpers used in and provided by the crate
+
 use cid::CidGeneric;
 use libp2p_core::multihash::Multihash;
 use libp2p_swarm::StreamProtocol;