Merge pull request #297 from alpenlabs/storopoli/fix-docs

docs: fix `cargo doc`, add to CI check, and `pr` recipe

.github/workflows/docs.yml

@@ -1,6 +1,8 @@
 name: Docs
 
 on:
+  pull_request:
+  merge_group:
   push:
     branches: [master]
 
@@ -20,14 +22,7 @@ jobs:
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
-      - run: cargo doc --document-private-items
+      - name: Check docs leaving the dependencies out
         env:
-          RUSTDOCFLAGS: --show-type-layout --enable-index-page -Zunstable-options -D warnings
-      - name: Compress docs artifacts
-        run: tar czf express-core-docs.tar.gz target/doc
-      - name: Archive docs
-        uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: docs
-          path: express-core-docs.tar.gz
+          RUSTDOCFLAGS: --show-type-layout --enable-index-page -Zunstable-options -A rustdoc::private-doc-tests -D warnings
+        run: cargo doc --workspace --no-deps

Makefile

@@ -180,10 +180,11 @@ rustdocs: ## Runs `cargo docs` to generate the Rust documents in the `target/doc
 	RUSTDOCFLAGS="\
 	--show-type-layout \
 	--enable-index-page -Z unstable-options \
+	-A rustdoc::private-doc-tests \
 	-D warnings" \
 	cargo doc \
 	--workspace \
-	--document-private-items
+	--no-deps
 
 .PHONY: test-doc
 test-doc: ## Runs doctests on the workspace.
@@ -195,7 +196,7 @@ test: ## Runs all tests in the workspace including unit and docs tests.
 	make test-doc
 
 .PHONY: pr
-pr: lint sec test-doc test-unit test-int test-functional ## Runs lints (without fixing), audit and tests (run this before creating a PR).
+pr: lint sec rustdocs test-doc test-unit test-int test-functional ## Runs lints (without fixing), audit, docs, and tests (run this before creating a PR).
 	@echo "\n\033[36m======== CHECKS_COMPLETE ========\033[0m\n"
 	@test -z "$$(git status --porcelain)" || echo "WARNNG: You have uncommitted changes"
 	@echo "All good to create a PR!"

crates/bridge-sig-manager/src/errors.rs

@@ -9,8 +9,8 @@ use thiserror::Error;
 /// [`Psbt`](bitcoin::Psbt).
 #[derive(Debug, Clone, Error)]
 pub enum BridgeSigError {
-    /// Failed to build a [`Psbt`] from the unsigned transaction. This can happen if the
-    /// transaction that is being converted to a psbt contains a non-empty script sig or
+    /// Failed to build a [`Psbt`](bitcoin::Psbt) from the unsigned transaction. This can happen if
+    /// the transaction that is being converted to a psbt contains a non-empty script sig or
     /// witness fields.
     #[error("build psbt: {0}")]
     PsbtConstruction(String),

crates/bridge-sig-manager/src/manager.rs

@@ -95,7 +95,7 @@ impl SignatureManager {
     ///
     /// If the state corresponding to the `txid` is not present in the database
     /// ([`BridgeSigError::TransactionNotFound`]). Or, if there is an error in the persistence layer
-    /// itself ([`BridgeSigError::StorageError`]).
+    /// itself ([`BridgeSigError::Storage`]).
     pub async fn get_tx_state(&self, txid: &Txid) -> BridgeSigResult<BridgeTxState> {
         let entry = self.db_ops.get_tx_state_async(*txid).await?;
 
@@ -143,7 +143,7 @@ impl SignatureManager {
 
     /// Add a nonce to the collection for given [`OperatorIdx`] and [`Txid`].
     ///
-    /// The [`OperatorIdx`] may even be the same as [`Self::index`] in which case the nonce is
+    /// The [`OperatorIdx`] may even be the same as `Self::index` in which case the nonce is
     /// updated. It is assumed that the upstream duty producer makes sure that the nonce only
     /// comes from a node authorized to produce that nonce.
     ///
@@ -256,7 +256,7 @@ impl SignatureManager {
 
     /// Add a partial signature for a [`BridgeTxState`].
     ///
-    /// The [`SignatureInfo::signer_index`] may even be the same as [`Self::index`] in which case
+    /// The [`OperatorPartialSig::signer_index`] may even be the same as `Self::index` in which case
     /// the nonce is updated. It is assumed that the upstream duty producer makes sure that the
     /// nonce only comes from a node authorized to produce that nonce.
     ///

crates/bridge-tx-builder/src/context.rs

@@ -32,8 +32,8 @@ pub struct TxBuildContext {
 }
 
 impl TxBuildContext {
-    /// Create a new [`TxBuilder`] with the context required to build transactions of various
-    /// [`TxKind`].
+    /// Create a new [`TxBuildContext`] with the context required to build transactions of various
+    /// [`TxKind`](super::TxKind).
     pub fn new(operator_pubkeys: PublickeyTable, network: Network) -> Self {
         let aggregated_pubkey = get_aggregated_pubkey(operator_pubkeys);
 

crates/bridge-tx-builder/src/deposit.rs

@@ -49,8 +49,8 @@ pub struct DepositInfo {
 
     /// The original taproot address in the Deposit Request Transaction (DRT) output used to
     /// sanity check computation internally i.e., whether the known information (n/n script spend
-    /// path, [`UNSPENDABLE_INTERNAL_KEY`]) + the [`Self::take_back_leaf_hash`] yields the same
-    /// P2TR address.
+    /// path, [`static@UNSPENDABLE_INTERNAL_KEY`]) + the [`Self::take_back_leaf_hash`] yields the
+    /// same P2TR address.
     original_taproot_addr: BitcoinAddress,
 }
 

crates/bridge-tx-builder/src/errors.rs

@@ -36,7 +36,7 @@ pub enum BridgeTxBuilderError {
     PsbtCreate(String),
 }
 
-/// Manual implementation of conversion from [`psbt::Error`] to [`BridgeTxStateError`] as the
+/// Manual implementation of conversion from [`psbt::Error`] to [`BridgeTxBuilderError`] as the
 /// former does not implement [`Clone`] ¯\_(ツ)_/¯.
 impl From<psbt::Error> for BridgeTxBuilderError {
     fn from(value: psbt::Error) -> Self {

crates/bridge-tx-builder/src/operations.rs

@@ -1,4 +1,4 @@
-//! Provides some common, standalone utilities and wrappers over [`bitcoin`](bitcoin) to create
+//! Provides some common, standalone utilities and wrappers over [`bitcoin`] to create
 //! scripts, addresses and transactions.
 
 use alpen_express_primitives::bridge::PublickeyTable;
@@ -69,7 +69,7 @@ pub enum SpendPath<'path> {
         internal_key: UntweakedPublicKey,
     },
     /// Script path spend that only allows spending via scripts in the taproot tree, with the
-    /// internal key being the [`UNSPENDABLE_INTERNAL_KEY`].
+    /// internal key being the [`static@UNSPENDABLE_INTERNAL_KEY`].
     ScriptSpend {
         /// The scripts that live in the leaves of the taproot tree.
         scripts: &'path [ScriptBuf],

crates/btcio/src/inscription.rs

@@ -208,7 +208,7 @@ impl InscriptionParser {
         Ok((tag, name))
     }
 
-    /// Parse [`InsriptionData`]
+    /// Parse [`InscriptionData`]
     ///
     /// # Errors
     ///

crates/btcio/src/lib.rs

@@ -1,5 +1,5 @@
-#![allow(dead_code)] // TODO: remove this once `get_height_blkid` and `deepest_block` are used.
 //! Input-output with Bitcoin, implementing L1 chain trait.
+#![allow(dead_code)] // TODO: remove this once `get_height_blkid` and `deepest_block` are used.
 
 pub mod broadcaster;
 pub mod inscription;

crates/btcio/src/rpc/error.rs

@@ -83,7 +83,7 @@ pub enum ClientError {
     #[error(transparent)]
     Sign(#[from] SignRawTransactionWithWalletError),
 
-    /// Could not get a [`Xpriv`] from the wallet
+    /// Could not get a [`Xpriv`](bitcoin::bip32::Xpriv) from the wallet
     #[error("Could not get xpriv from wallet")]
     Xpriv,
 

crates/btcio/src/rpc/traits.rs

@@ -88,7 +88,7 @@ pub trait Broadcaster {
 /// Wallet functionality that any Bitcoin client **without private keys** that
 /// interacts with the Bitcoin network should provide.
 ///
-/// For signing transactions, see [`BitcoinSigner`].
+/// For signing transactions, see [`Signer`].
 ///
 /// # Note
 ///

crates/consensus-logic/src/state_tracker.rs

@@ -93,8 +93,10 @@ impl<D: Database> StateTracker<D> {
 }
 
 /// Reconstructs the [`ClientState`] by fetching the last available checkpoint
-/// and replaying all relevant [`ClientStateWrite`]s from that checkpoint
-/// up to the specified index `idx`, ensuring an accurate and up-to-date state.
+/// and replaying all relevant
+/// [`ClientStateWrite`](alpen_express_state::operation::ClientStateWrite)
+/// from that checkpoint up to the specified index `idx`,
+/// ensuring an accurate and up-to-date state.
 ///
 /// # Parameters
 ///
@@ -123,10 +125,11 @@ pub fn reconstruct_cur_state(
     Ok((last_write_idx, state))
 }
 
-/// Reconstructs the `[ClientState`].
+/// Reconstructs the
+/// [`ClientStateWrite`](alpen_express_state::operation::ClientStateWrite)
 ///
 /// Under the hood fetches the last available checkpoint
-/// and then replays all the [`ClientStateWrite`]s
+/// and then replays all the [`ClientStateWrite`](alpen_express_state::operation::ClientStateWrite)s
 /// from that checkpoint up to the requested index `idx`
 /// such that we have accurate [`ClientState`].
 ///

crates/db/src/entities/bridge_tx_state.rs

@@ -1,5 +1,5 @@
 //! Defines the [`BridgeTxState`] type that tracks the state of signature collection for a
-//! particular [`Psbt`].
+//! particular [`Psbt`](bitcoin::Psbt).
 
 use std::{collections::BTreeMap, ops::Not};
 
@@ -28,7 +28,7 @@ pub struct BridgeTxState {
     spend_infos: Vec<SpendInfo>,
 
     /// The table of pubkeys that is used to lock the UTXO present as an input in the psbt.
-    /// This table maps the `OperatorIdx` to their corresponding pubkeys.
+    /// This table maps the [`OperatorIdx`] to their corresponding pubkeys.
     pubkey_table: PublickeyTable,
 
     /// The private nonce unique to the transaction being tracked by this state.
@@ -37,16 +37,17 @@ pub struct BridgeTxState {
     // For more on nonce security, see [this](https://docs.rs/musig2/latest/musig2/#security).
     secnonce: Musig2SecNonce,
 
-    /// The (public) nonces shared for the particular [`Psbt`] that this state tracks under MuSig2.
+    /// The (public) nonces shared for the particular [`Psbt`](bitcoin::Psbt)
+    /// that this state tracks under MuSig2.
     collected_nonces: BTreeMap<OperatorIdx, Musig2PubNonce>,
 
     /// The table of signatures collected so far per operator and per input in the [`Self::psbt`].
     collected_sigs: Vec<PartialSigTable>,
 }
 
 impl BridgeTxState {
-    /// Create a new [`TxState`] for the given [`Psbt`] and list of
-    /// [`bitcoin::secp256k1::PublicKey`].
+    /// Create a new [`BridgeTxState`] for the given [`Psbt`](bitcoin::Psbt)
+    /// and list of [`bitcoin::secp256k1::PublicKey`].
     pub fn new(
         tx_signing_data: TxSigningData,
         pubkey_table: PublickeyTable,
@@ -68,17 +69,18 @@ impl BridgeTxState {
         })
     }
 
-    /// Get the [`Psbt`] that this state is associated with.
+    /// Get the [`Psbt`](bitcoin::Psbt) that this state is associated with.
     pub fn psbt(&self) -> &BitcoinPsbt {
         &self.psbt
     }
 
-    /// Get the spend info associated with each input in the PSBT.
+    /// Get the spend info associated with each input in the [`Psbt`](bitcoin::Psbt).
     pub fn spend_infos(&self) -> &[SpendInfo] {
         &self.spend_infos[..]
     }
 
-    /// Get the relevant previous outputs of the Psbt that this state tracks.
+    /// Get the relevant previous outputs of the [`Psbt`](bitcoin::Psbt)
+    /// that this state tracks.
     pub fn prevouts(&self) -> Vec<TxOut> {
         self.psbt()
             .inner()
@@ -93,7 +95,8 @@ impl BridgeTxState {
             .collect()
     }
 
-    /// Get the number of required signatures for the [`Psbt`] to be considered fully signed.
+    /// Get the number of required signatures for the [`Psbt`](bitcoin::Psbt)
+    /// to be considered fully signed.
     pub fn required_signatures(&self) -> usize {
         self.pubkey_table.0.keys().len()
     }
@@ -109,7 +112,7 @@ impl BridgeTxState {
         &self.pubkey_table
     }
 
-    /// Get the unsigned transaction from the [`Psbt`].
+    /// Get the unsigned transaction from the [`Psbt`](bitcoin::Psbt).
     pub fn unsigned_tx(&self) -> &Transaction {
         &self.psbt().inner().unsigned_tx
     }
@@ -162,7 +165,8 @@ impl BridgeTxState {
         Ok(self.has_all_nonces())
     }
 
-    /// Check if all the required signatures have been collected for the [`Psbt`].
+    /// Check if all the required signatures have been collected for the
+    /// [`Psbt`](bitcoin::Psbt).
     pub fn is_fully_signed(&self) -> bool {
         // for each input, check all signatures have been collected
         // each signature is added only if the signer is part of the `pubkey_table`,
@@ -178,7 +182,7 @@ impl BridgeTxState {
     /// **Note**: This being a database-related operation, no validation is performed on the
     /// provided signature as that requires access to a signing module. The only validation that
     /// this method performs is that the signature comes from an [`OperatorIdx`] that is part of
-    /// the [`Self::pubkey_table`]. It is assumed that all necessary validation has already been
+    /// the `Self::pubkey_table`. It is assumed that all necessary validation has already been
     /// performed at the callsite.
     ///
     /// # Returns
@@ -188,8 +192,8 @@ impl BridgeTxState {
     ///
     /// # Errors
     ///
-    /// If the [`SignatureInfo::signer_index`] is not a part of the required signatories or the
-    /// `input_index` is not part of the [`Psbt`].
+    /// If the [`OperatorPartialSig::signer_index`] is not a part of the required signatories or the
+    /// `input_index` is not part of the [`Psbt`](bitcoin::Psbt).
     pub fn add_signature(
         &mut self,
         signature_info: OperatorPartialSig,

crates/db/src/traits.rs

@@ -381,7 +381,7 @@ pub trait BcastProvider {
 /// Provides access to the implementers of provider and store traits for interacting with the
 /// transaction state database of the bridge client.
 ///
-/// This trait assumes that the [`Txid`] is always unique.
+/// This trait assumes that the [`Txid`](bitcoin::Txid) is always unique.
 pub trait BridgeTxDatabase {
     /// Add [`BridgeTxState`] to the database replacing the existing one if present.
     fn put_tx_state(&self, txid: Buf32, tx_state: BridgeTxState) -> DbResult<()>;

crates/db/src/types.rs

@@ -86,7 +86,7 @@ impl L1TxEntry {
     ///
     /// # Note
     ///
-    /// Whenever possible use [`to_tx()`] to deserialize the transaction.
+    /// Whenever possible use [`try_to_tx()`](L1TxEntry::try_to_tx) to deserialize the transaction.
     /// This imposes more strict type checks.
     pub fn tx_raw(&self) -> &[u8] {
         &self.tx_raw

crates/proof-impl/btc-blockspace/src/block.rs

@@ -86,7 +86,7 @@ pub fn compute_witness_root(l1_tx: &L1Tx) -> Buf32 {
     Buf32::from(cur_hash)
 }
 
-/// Checks if witness commitment in coinbase matches the corresponding [`L1Tx`](L1Tx).
+/// Checks if witness commitment in coinbase matches the corresponding [`L1Tx`].
 pub fn check_witness_commitment(block: &Block, l1_tx: &L1Tx) -> bool {
     if block.txdata.is_empty() {
         return false;

crates/proof-impl/evm-ee-stf/src/db.rs

@@ -31,9 +31,9 @@ use crate::{
     ELProofInput,
 };
 
-/// A helper trait to extend [InMemoryDB] with additional functionality.
+/// A helper trait to extend [`InMemoryDB`] with additional functionality.
 pub trait InMemoryDBHelper {
-    /// Create an [InMemoryDB] from a given [SP1RethInput].
+    /// Create an [`InMemoryDB`] from a given [`ELProofInput`].
     fn initialize(input: &mut ELProofInput) -> Result<Self>
     where
         Self: Sized;

crates/proof-impl/evm-ee-stf/src/lib.rs

@@ -15,7 +15,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-
 pub mod db;
 pub mod mpt;
 pub mod processor;

crates/proof-impl/evm-ee-stf/src/processor.rs

@@ -15,7 +15,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-
 use std::{mem, mem::take};
 
 use alloy_eips::eip1559::BaseFeeParams;
@@ -68,7 +67,7 @@ pub struct EvmProcessor<D> {
 impl<D> EvmProcessor<D> {
     /// Validate the header standalone.
     ///
-    /// Reference: https://github.com/paradigmxyz/reth/blob/main/crates/consensus/common/src/validation.rs#L14
+    /// Reference: <https://github.com/paradigmxyz/reth/blob/main/crates/consensus/common/src/validation.rs#L14>
     pub fn validate_header_standalone(&self) {
         let header = self.header.as_ref().unwrap();
 
@@ -80,7 +79,7 @@ impl<D> EvmProcessor<D> {
 
     /// Validates the integrity and consistency of a block header in relation to it's parent.
     ///
-    /// Reference: https://github.com/paradigmxyz/reth/blob/main/crates/primitives/src/header.rs#L800
+    /// Reference: <https://github.com/paradigmxyz/reth/blob/main/crates/primitives/src/header.rs#L800>
     pub fn validate_against_parent(&self) {
         let parent_header = &self.input.parent_header;
         let header = self.header.as_ref().unwrap();
@@ -103,7 +102,7 @@ impl<D> EvmProcessor<D> {
 
     /// Checks the gas limit for consistency between parent and self headers.
     ///
-    /// Reference: https://github.com/paradigmxyz/reth/blob/main/crates/primitives/src/header.rs#L738
+    /// Reference: <https://github.com/paradigmxyz/reth/blob/main/crates/primitives/src/header.rs#L738>
     pub fn validate_gas_limit(&self) {
         let parent_header = &self.input.parent_header;
         let header = self.header.as_ref().unwrap();
@@ -127,7 +126,7 @@ impl<D> EvmProcessor<D> {
 
     /// Validates the header's extradata according to the beacon consensus rules.
     ///
-    /// Reference: https://github.com/paradigmxyz/reth/blob/main/crates/consensus/beacon-core/src/lib.rs#L118
+    /// Reference: <https://github.com/paradigmxyz/reth/blob/main/crates/consensus/beacon-core/src/lib.rs#L118>
     pub fn validate_header_extradata(&self) {
         let header = self.header.as_ref().unwrap();
         if header.extra_data.len() > MAXIMUM_EXTRA_DATA_SIZE {