Merge #392

392: Refresh docs r=koivunej a=koivunej

Adds at least top level documentation for many types, hides some unnecessary re-exports, removes warnings from nightly rustdoc on bad links, and so on.

Cc: #197 (this leaves us with 185 errors)

Co-authored-by: Joonas Koivunen <joonas@equilibrium.co>
Co-authored-by: Joonas Koivunen <joonas.koivunen@gmail.com>

Author: 3 people

bitswap/src/behaviour.rs

@@ -26,13 +26,15 @@ use std::{
     },
 };
 
+/// Event used to communicate with the swarm or the higher level behaviour.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub enum BitswapEvent {
     ReceivedBlock(PeerId, Block),
     ReceivedWant(PeerId, Cid, Priority),
     ReceivedCancel(PeerId, Cid),
 }
 
+/// Bitswap statistics.
 #[derive(Debug, Default)]
 pub struct Stats {
     pub sent_blocks: AtomicU64,

bitswap/src/block.rs

@@ -1,8 +1,14 @@
 use cid::Cid;
 
+/// An Ipfs block consisting of a [`Cid`] and the bytes of the block.
+///
+/// Note: At the moment the equality is based on [`Cid`] equality, which is based on the triple
+/// `(cid::Version, cid::Codec, multihash)`.
 #[derive(Clone, Debug)]
 pub struct Block {
+    /// The content identifier for this block
     pub cid: Cid,
+    /// The data of this block
     pub data: Box<[u8]>,
 }
 
@@ -11,6 +17,7 @@ impl PartialEq for Block {
         self.cid.hash() == other.cid.hash()
     }
 }
+
 impl Eq for Block {}
 
 impl Block {

http/README.md

@@ -1,14 +1,18 @@
 # ipfs-http crate
 
-HTTP api on top of ipfs crate. The end binary has some rudimentary ipfs CLI
+HTTP api on top of `ipfs` crate. The end binary has some rudimentary ipfs CLI
 functionality but mostly in the aim of testing the `rust-ipfs` via:
 
- * [ipfs-rust-conformance](https://github.com/rs-ipfs/ipfs-rust-conformance)
+ * [conformance](../conformance)
  * [interop](https://github.com/rs-ipfs/interop/)
 
+The vision for this crate is to eventually provide warp filters and async
+methods suitable to providing the Ipfs HTTP API in other applications as well
+instead of having to write application specific debug and introspection APIs.
+
 HTTP specs:
 
- * https://docs.ipfs.io/reference/api/http/
+ * https://docs.ipfs.io/reference/http/api/
 
 Status: Pre-alpha, most of the functionality is missing or `501 Not
 Implemented`. See the repository level README for more information.

http/src/config.rs

@@ -1,4 +1,4 @@
-//! go-ipfs compatible configuration file handling or at least setup.
+//! go-ipfs compatible configuration file handling and setup.
 
 use parity_multiaddr::Multiaddr;
 use serde::{Deserialize, Serialize};

http/src/lib.rs

@@ -1,3 +1,8 @@
+//! `ipfs-http` http API implementation.
+//!
+//! This crate is most useful as a binary used first and foremost for compatibility testing against
+//! other ipfs implementations.
+
 #[macro_use]
 extern crate tracing;
 

http/src/v0.rs

@@ -1,3 +1,7 @@
+//! Implementation of `/api/v0` HTTP endpoints.
+//!
+//! See https://docs.ipfs.io/reference/http/api/ for more information.
+
 use ipfs::{Ipfs, IpfsTypes};
 use warp::{query, Filter};
 

src/dag.rs

@@ -1,3 +1,5 @@
+//! `ipfs.dag` interface implementation around [`Ipfs`].
+
 use crate::error::Error;
 use crate::ipld::{decode_ipld, encode_ipld, Ipld};
 use crate::path::{IpfsPath, SlashedPath};
@@ -854,7 +856,7 @@ mod tests {
         // FIXME: validate that go-ipfs still does this
         let equiv_paths = vec![
             prefix.sub_path("0/0").unwrap(),
-            prefix.into_sub_path("0/./0").unwrap(),
+            prefix.sub_path("0/./0").unwrap(),
         ];
 
         for p in equiv_paths {

src/error.rs

@@ -1,3 +1,17 @@
+//! Crate-wide errors.
+//!
+//! The error handling in `ipfs` is subject to change in the future.
+
+/// Just re-export anyhow for now.
+///
+/// # Stability
+///
+/// Very likely to change in the future.
 pub use anyhow::Error;
 
+/// A try conversion failed.
+///
+/// # Stability
+///
+/// Very likely to change in the future.
 pub struct TryError;

src/ipld/ipld_macro.rs

@@ -1,3 +1,5 @@
+/// Easy to use nested [`crate::ipld::Ipld`] creation with syntax similar to
+/// [`serde_json::json`](https://docs.rs/serde_json/1.0/serde_json/macro.json.html) macro.
 #[macro_export(local_inner_macros)]
 macro_rules! make_ipld {
     // Hide distracting implementation details from the generated rustdoc.

src/ipld/mod.rs

@@ -1,7 +1,9 @@
-// This code was adapted from https://github.com/ipfs-rust/rust-ipld, and most of
-// its code is the same as at revision b2286c53c13f3eeec2a3766387f2926838e8e4c9;
-// it used to be a direct dependency, but recent updates to cid and multihash crates
-// made it incompatible with them.
+//! IPLD dag-json, dag-cbor and some dag-pb functionality.
+//!
+//! This code was adapted from https://github.com/ipfs-rust/rust-ipld, and most of
+//! its code is the same as at revision b2286c53c13f3eeec2a3766387f2926838e8e4c9;
+//! it used to be a direct dependency, but recent updates to cid and multihash crates
+//! made it incompatible with them.
 
 pub mod dag_cbor;
 pub mod dag_json;