doc: fix cargo doc warnings

src/bin/neptune-cli.rs

@@ -82,7 +82,7 @@ enum Command {
     OwnInstanceId,
     BlockHeight,
     BlockInfo {
-        /// one of: genesis, tip, height/<n>, digest/<hex>
+        /// one of: `genesis, tip, height/<n>, digest/<hex>`
         block_selector: BlockSelector,
     },
     Confirmations,
@@ -94,7 +94,7 @@ enum Command {
     },
     TipHeader,
     Header {
-        /// one of: genesis, tip, height/<n>, digest/<hex>
+        /// one of: `genesis, tip, height/<n>, digest/<hex>`
         block_selector: BlockSelector,
     },
     SyncedBalance,

src/database/neptune_leveldb.rs

@@ -154,7 +154,7 @@ where
 }
 
 /// `NeptuneLevelDb` provides an async-friendly and clone-friendly wrapper
-/// around [`NeptuneLevelDbInternal`].
+/// around `NeptuneLevelDbInternal`.
 ///
 /// Methods in the underlying struct `LevelDB` from `rs-leveldb` crate are all sync
 /// and they sometimes perfom blocking file IO.  It is discouraged to

src/database/storage/storage_schema/schema.rs

@@ -22,48 +22,8 @@ use std::{fmt::Display, sync::Arc};
 /// This can be achieved by placing the `table`s into a heterogenous
 /// container such as a `struct` or `tuple`. Then place an
 /// `Arc<Mutex<..>>` or `Arc<Mutex<RwLock<..>>` around the container.
-///
-/// # Example:
-///
-/// ```compile_fail
-/// # // note: compile_fail due to: https://github.com/rust-lang/rust/issues/67295
-/// # tokio_test::block_on(async {
-/// # use database::storage::{storage_vec::traits::*, storage_schema::{SimpleRustyStorage, traits::*}};
-/// # let db = database::NeptuneLevelDb::open_new_test_database(true, None, None, None).await.unwrap();
-/// use std::sync::Arc;
-/// use tokio::sync::RwLock;
-/// let mut storage = SimpleRustyStorage::new(db);
-///
-/// let tables = (
-///     storage.schema.new_vec::<u16>("ages").await,
-///     storage.schema.new_vec::<String>("names").await,
-///     storage.schema.new_singleton::<bool>("proceed").await
-/// );
-///
-/// let mut atomic_tables = Arc::new(RwLock::new(tables));
-///
-/// // these mutations happen atomically in mem.
-/// {
-///     let mut lock = atomic_tables.write().await;
-///     lock.0.push(5).await;
-///     lock.1.push("Sally".into()).await;
-///     lock.2.set(true).await;
-/// }
-///
-/// // all pending writes are persisted to DB in one atomic batch operation.
-/// storage.persist();
-/// # });
-/// ```
-///
-/// In the example, the `table` were placed in a `tuple` container.
-/// It works equally well to put them in a `struct`.  If the tables
-/// are all of the same type (including generics), they could be
-/// placed in a collection type such as `Vec`, or `HashMap`.
-///
-/// This crate provides [`AtomicRw`] and [`AtomicMutex`]
+/// This crate provides [`AtomicRw`] and [`AtomicMutex`](crate::locks::tokio::AtomicMutex)
 /// which are simple wrappers around `Arc<RwLock<T>>` and `Arc<Mutex<T>>`.
-/// `DbtSchema` provides helper methods for wrapping your `table`s with
-/// these.
 ///
 /// This is the recommended usage.
 ///
@@ -98,6 +58,11 @@ use std::{fmt::Display, sync::Arc};
 /// storage.persist();
 /// # });
 /// ```
+///
+/// In the example, the `table` were placed in a `tuple` container.
+/// It works equally well to put them in a `struct`.  If the tables
+/// are all of the same type (including generics), they could be
+/// placed in a collection type such as `Vec`, or `HashMap`.
 pub struct DbtSchema {
     /// Pending writes for all tables in this Schema.
     /// These get written/cleared by StorageWriter::persist()
@@ -110,7 +75,7 @@ pub struct DbtSchema {
 
     /// If present, the provided callback function will be called
     /// whenever a lock is acquired by a `DbTable` instantiated
-    /// by this `DbtSchema`.  See [AtomicRw](crate::sync::AtomicRw)
+    /// by this `DbtSchema`.  See [AtomicRw]
     pub lock_callback_fn: Option<LockCallbackFn>,
 
     /// indicates count of tables in this schema
@@ -120,7 +85,7 @@ pub struct DbtSchema {
 impl DbtSchema {
     /// Instantiate a `DbtSchema` from a `SimpleRustyReader` and
     /// optional `name` and lock acquisition callback.
-    /// See [AtomicRw](crate::sync::AtomicRw)
+    /// See [AtomicRw]
     pub fn new(
         reader: SimpleRustyReader,
         name: Option<&str>,

src/database/storage/storage_vec/ordinary_vec.rs

@@ -4,7 +4,7 @@ use serde::Serialize;
 use super::ordinary_vec_private::OrdinaryVecPrivate;
 use super::{traits::*, Index};
 
-/// Implements [`StorageVec`]` trait for an ordinary (in memory) `Vec`
+/// Implements [`StorageVec`] trait for an ordinary (in memory) `Vec`
 #[derive(Debug, Clone, Default)]
 pub struct OrdinaryVec<T>(OrdinaryVecPrivate<T>);
 

src/locks/std/traits.rs

@@ -1,4 +1,4 @@
-//! Traits that define the [`sync`](crate::sync) interface
+//! Traits that define the [`locks::std`](crate::locks::std) interface
 
 pub trait Atomic<T> {
     /// Immutably access the data of type `T` in a closure and possibly return a result of type `R`

src/models/blockchain/block/block_selector.rs

@@ -32,10 +32,12 @@ pub enum BlockSelector {
 }
 
 /// BlockSelector can be written out as any of:
+/// ```
 ///  genesis
 ///  tip
 ///  height/<N>
 ///  digest/<hex>
+/// ```
 ///
 /// This is intended to be easy for humans to read and also input, ie suitable
 /// for use as CLI argument.

src/models/blockchain/type_scripts/time_lock.rs

@@ -493,7 +493,7 @@ impl From<transaction::primitive_witness::PrimitiveWitness> for TimeLockWitness
 
 impl Arbitrary for TimeLockWitness {
     /// Parameters are:
-    ///  - release_dates : Vec<u64> One release date per input UTXO. 0 if the time lock
+    ///  - release_dates : `Vec<u64>` One release date per input UTXO. 0 if the time lock
     ///    coin is absent.
     ///  - num_outputs : usize Number of outputs.
     ///  - num_public_announcements : usize Number of public announcements.

src/models/consensus/tasm/program.rs

@@ -26,7 +26,7 @@ where
 {
     /// The canonical reference source code for the consensus program, written in the
     /// subset of rust that the tasm-lang compiler understands. To run this program, call
-    /// [`run`][`run`], which spawns a new thread, boots the environment, and executes
+    /// [ConsensusProgram::run()], which spawns a new thread, boots the environment, and executes
     /// the program.
     fn source(&self);