feat: private doctests

.config/forest.dic

@@ -74,5 +74,6 @@ validator/S
 verifier
 VM
 VRF
+WebAssembly
 WebSocket
 zstd

Cargo.toml

@@ -223,6 +223,7 @@ overflow-checks = true
 default = ["paritydb", "jemalloc", "fil_cns"]
 instrumented_kernel = ["dep:stdext"]
 insecure_post = []
+doctest-private = []                          # see lib.rs::doctest_private
 
 # Databases
 paritydb = ["dep:parity-db"]

Makefile

@@ -113,7 +113,8 @@ test:
 	cargo nextest run --features=rocksdb,rustalloc,fil_cns  --no-default-features db
 
 	# nextest doesn't run doctests https://github.com/nextest-rs/nextest/issues/16
-	cargo test --doc
+	# see also lib.rs::doctest_private
+	cargo test --doc --features doctest-private
 
 test-release:
 	cargo nextest run --release

src/blocks/header/mod.rs

@@ -32,12 +32,10 @@ pub mod json;
 ///
 /// Usage:
 /// ```
-/// use forest_filecoin::blocks::{BlockHeader, TipsetKeys, Ticket};
-/// use forest_filecoin::shim::address::Address;
+/// # use forest_filecoin::doctest_private::{BlockHeader, TipsetKeys, Ticket, Signature, Address};
 /// use cid::Cid;
 /// use cid::multihash::Code::Identity;
 /// use num::BigInt;
-/// use forest_filecoin::shim::crypto::Signature;
 /// use fvm_ipld_encoding::DAG_CBOR;
 /// use cid::multihash::MultihashDigest;
 ///

src/cli/humantoken.rs

@@ -121,9 +121,10 @@ mod parse {
 
     /// Parse token amounts as floats with SI prefixed-units.
     /// ```
+    /// # use forest_filecoin::doctest_private::{TokenAmount, parse};
     /// fn assert_attos(input: &str, attos: u64) {
-    ///     let expected = forest_filecoin::shim::econ::TokenAmount::from_atto(attos);
-    ///     let actual = forest_filecoin::cli::humantoken::parse(input).unwrap();
+    ///     let expected = TokenAmount::from_atto(attos);
+    ///     let actual = parse(input).unwrap();
     ///     assert_eq!(expected, actual);
     /// }
     /// assert_attos("1a", 1);
@@ -407,9 +408,9 @@ mod print {
         /// - `{:.#4}`: both
         ///
         /// ```
-        /// use forest_filecoin::cli::humantoken::TokenAmountPretty as _;
+        /// # use forest_filecoin::doctest_private::{TokenAmountPretty as _, TokenAmount};
         ///
-        /// let amount = forest_filecoin::shim::econ::TokenAmount::from_nano(1500);
+        /// let amount = TokenAmount::from_nano(1500);
         ///
         /// // Defaults to precise, with SI prefix
         /// assert_eq!("1500 nanoFIL", format!("{}", amount.pretty()));

src/lib.rs

@@ -23,38 +23,61 @@ cfg_if::cfg_if! {
     }
 }
 
-pub mod auth;
-pub mod beacon;
-pub mod blocks;
-pub mod chain;
-pub mod chain_sync;
-pub mod cli;
-pub mod cli_shared;
-pub mod daemon;
-pub mod db;
-pub mod deleg_cns;
-pub mod fil_cns;
-pub mod genesis;
-pub mod interpreter;
-pub mod ipld;
-pub mod json;
-pub mod key_management;
-pub mod libp2p;
-pub mod libp2p_bitswap;
-pub mod message;
-pub mod message_pool;
-pub mod metrics;
-pub mod networks;
-pub mod rpc;
-pub mod rpc_api;
-pub mod rpc_client;
-pub mod shim;
-pub mod state_manager;
-pub mod state_migration;
-pub mod statediff;
-pub mod test_utils;
-pub mod utils;
+mod auth;
+mod beacon;
+mod blocks;
+mod chain;
+mod chain_sync;
+mod cli;
+mod cli_shared;
+mod daemon;
+mod db;
+mod deleg_cns;
+mod fil_cns;
+mod genesis;
+mod interpreter;
+mod ipld;
+mod json;
+mod key_management;
+mod libp2p;
+mod libp2p_bitswap;
+mod message;
+mod message_pool;
+mod metrics;
+mod networks;
+mod rpc;
+mod rpc_api;
+mod rpc_client;
+mod shim;
+mod state_manager;
+mod state_migration;
+mod statediff;
+mod test_utils;
+mod utils;
 
+/// These items are semver-exempt, and exist for forest author use only
+// We want to have doctests, but don't want our internals to be public because:
+// - We don't want to be concerned with library compat
+//   (We want our cargo semver to be _for the command line_).
+// - We don't want to mistakenly export items which we never actually use.
+//
+// So we re-export the relevant items and test with `cargo test --doc --features doctest-private`
+#[cfg(feature = "doctest-private")]
+#[doc(hidden)]
+pub mod doctest_private {
+    pub use crate::{
+        blocks::{BlockHeader, Ticket, TipsetKeys},
+        cli::humantoken::{parse, TokenAmountPretty},
+        shim::{
+            address::Address, crypto::Signature, econ::TokenAmount, error::ExitCode,
+            randomness::Randomness, sector::RegisteredSealProof, state_tree::ActorState,
+            version::NetworkVersion, Inner,
+        },
+        utils::{encoding::blake2b_256, io::read_toml},
+    };
+}
+
+// These should be made private in https://github.com/ChainSafe/forest/issues/3013
 pub use auth::{verify_token, JWT_IDENTIFIER};
 pub use cli::main::main as forest_main;
 pub use cli_shared::cli::{Client, Config};

src/libp2p_bitswap/mod.rs

@@ -1,7 +1,29 @@
 // Copyright 2019-2023 ChainSafe Systems
 // SPDX-License-Identifier: Apache-2.0, MIT
-
-#![doc = include_str!("./README.md")]
+//! Another libp2p
+//! bitswap([SPEC](https://github.com/ipfs/specs/blob/main/BITSWAP.md))
+//! implementation in Rust.
+//!
+//! ## Features
+//!
+//! - Compatible with [`go-bitswap`](https://github.com/ipfs/go-bitswap)
+//! - Optional request manager
+//! - Prometheus metrics
+//! - Multiple async task API support, `async-std` and `tokio`(optional behind
+//!   feature `tokio`)
+//! - Compiles into WebAssembly and works in browser.
+//!   (`examples/bitswap-in-browser`)
+//!
+//! ## Usage
+//!
+//! Basic usage of `BitswapBehaviour`, for writing swarm event flow, sending or
+//! receiving a request or a response, checkout `tests/go_compat.rs`. Note that a
+//! request manager is needed for a real-world application.
+//!
+//! To use the builtin request manager that is optimized for Filecoin network, a
+//! data store that implements `BitswapStoreRead` and `BitswapStoreReadWrite` is
+//! required. For hooking request manager in swarm event flow, requesting a block
+//! via request manager API, checkout `tests/request_manager.rs`.
 
 use std::io::Result as IOResult;
 

src/shim/error.rs

@@ -12,11 +12,12 @@ use crate::shim::Inner;
 ///
 /// # Examples
 /// ```
+/// # use forest_filecoin::doctest_private::ExitCode;
 /// let fvm2_success = fvm_shared::error::ExitCode::new(0);
 /// let fvm3_success = fvm_shared3::error::ExitCode::new(0);
 ///
-/// let shim_from_v2 = forest_filecoin::shim::error::ExitCode::from(fvm2_success);
-/// let shim_from_v3 = forest_filecoin::shim::error::ExitCode::from(fvm3_success);
+/// let shim_from_v2 = ExitCode::from(fvm2_success);
+/// let shim_from_v3 = ExitCode::from(fvm3_success);
 ///
 /// assert_eq!(shim_from_v2, shim_from_v3);
 /// assert_eq!(shim_from_v2, fvm2_success.into());

src/shim/mod.rs

@@ -22,8 +22,7 @@ pub mod version;
 /// The usage is awkward but it avoids code duplication.
 ///
 /// ```
-/// use forest_filecoin::shim::Inner;
-/// use forest_filecoin::shim::error::ExitCode;
+/// # use forest_filecoin::doctest_private::{Inner, ExitCode};
 /// <ExitCode as Inner>::FVM::new(0);
 /// ```
 pub trait Inner {

src/shim/randomness.rs

@@ -12,6 +12,7 @@ use serde::{Deserialize, Serialize};
 ///
 /// # Examples
 /// ```
+/// # use forest_filecoin::doctest_private::Randomness;
 ///
 /// // Create FVM2 Randomness normally
 /// let fvm2_rand = fvm_shared::randomness::Randomness(vec![]);
@@ -20,7 +21,7 @@ use serde::{Deserialize, Serialize};
 /// let fvm3_rand = fvm_shared3::randomness::Randomness(vec![]);
 ///
 /// // Create a shim Randomness, ensure conversions are correct
-/// let rand_shim = forest_filecoin::shim::randomness::Randomness::new(vec![]);
+/// let rand_shim = Randomness::new(vec![]);
 /// assert_eq!(fvm3_rand, *rand_shim);
 /// assert_eq!(fvm2_rand, rand_shim.into());
 /// ```

src/shim/sector.rs

@@ -20,15 +20,15 @@ use crate::shim::{version::NetworkVersion, Inner};
 ///
 /// # Examples
 /// ```
-///
+/// # use forest_filecoin::doctest_private::RegisteredSealProof;
 /// // Create FVM2 RegisteredSealProof normally
 /// let fvm2_proof = fvm_shared::sector::RegisteredSealProof::StackedDRG2KiBV1;
 ///
 /// // Create a correspndoning FVM3 RegisteredSealProof
 /// let fvm3_proof = fvm_shared3::sector::RegisteredSealProof::StackedDRG2KiBV1;
 ///
 /// // Create a shim out of fvm2 proof, ensure conversions are correct
-/// let proof_shim = forest_filecoin::shim::sector::RegisteredSealProof::from(fvm2_proof);
+/// let proof_shim = RegisteredSealProof::from(fvm2_proof);
 /// assert_eq!(fvm3_proof, *proof_shim);
 /// assert_eq!(fvm2_proof, proof_shim.into());
 /// ```

src/shim/state_tree.rs

@@ -207,6 +207,7 @@ where
 ///
 /// # Examples
 /// ```
+/// # use forest_filecoin::doctest_private::ActorState;
 /// use cid::Cid;
 ///
 /// // Create FVM2 ActorState normally
@@ -218,7 +219,7 @@ where
 /// fvm_shared3::econ::TokenAmount::from_atto(42), 0, None);
 ///
 /// // Create a shim out of fvm2 state, ensure conversions are correct
-/// let state_shim = forest_filecoin::shim::state_tree::ActorState::from(fvm2_actor_state.clone());
+/// let state_shim = ActorState::from(fvm2_actor_state.clone());
 /// assert_eq!(fvm3_actor_state, *state_shim);
 /// assert_eq!(fvm2_actor_state, state_shim.into());
 /// ```

src/shim/version.rs

@@ -10,7 +10,8 @@ use serde::{Deserialize, Serialize};
 ///
 /// # Examples
 /// ```
-/// let v0 = forest_filecoin::shim::version::NetworkVersion::V0;
+/// # use forest_filecoin::doctest_private::NetworkVersion;
+/// let v0 = NetworkVersion::V0;
 ///
 /// // dereference to convert to FVM3
 /// assert_eq!(fvm_shared3::version::NetworkVersion::V0, *v0);

src/utils/encoding/mod.rs

@@ -54,7 +54,7 @@ pub mod serde_byte_array {
 ///
 /// # Example
 /// ```
-/// use forest_filecoin::utils::encoding::blake2b_256;
+/// # use forest_filecoin::doctest_private::blake2b_256;
 ///
 /// let ingest: Vec<u8> = vec![];
 /// let hash = blake2b_256(&ingest);

src/utils/io/mod.rs

@@ -71,7 +71,7 @@ pub fn read_file_to_string(path: &Path) -> Result<String> {
 /// # Example
 /// ```
 /// use serde::Deserialize;
-/// use forest_filecoin::utils::io::read_toml;
+/// use forest_filecoin::doctest_private::read_toml;
 ///
 /// #[derive(Deserialize)]
 /// struct Config {