Merge #384: Enable building docs in the CI pipeline

c40d350 CI: Build the docs (Tobin C. Harding)
3ff4f14 Fix docs links (Tobin C. Harding)
432c49b Remove reference to private types (Tobin C. Harding)

Pull request description:

  First fix all the docs build errors then enable docs build in CI, as we do in other crates in our stack.

ACKs for top commit:
  apoelstra:
    ACK c40d350
  sanket1729:
    re-ACK c40d350

Tree-SHA512: d5370db7db6a3f2fa7cfbacc8fa4c55073c42c353fb763c19d0f42a3abfe7362ffb9eb97b3fa20399481a2cbe45e2962c092249be06197b37f5839db55deaa5b

Author: sanket1729

.github/workflows/rust.yml

@@ -27,26 +27,26 @@ jobs:
           DO_LINT: true
         run: ./contrib/test.sh
 
-  bench_nightly:
-    name: Bench + Tests
+  Nightly:
+    name: Bench + Docs
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        rust:
-          - nightly
     steps:
       - name: Checkout Crate
         uses: actions/checkout@v2
       - name: Checkout Toolchain
         uses: actions-rs/toolchain@v1
         with:
           profile: minimal
-          toolchain: ${{ matrix.rust }}
+          toolchain: nightly
           override: true
-      - name: Running cargo test
+      - name: Running benchmarks
         env:
           DO_BENCH: true
         run: ./contrib/test.sh
+      - name: Building docs
+        env:
+          DO_DOCS: true
+        run: ./contrib/test.sh
 
   UnitTests:
     name: Tests

contrib/test.sh

@@ -44,12 +44,17 @@ cargo build --examples
 # run all examples
 run-parts ./target/debug/examples
 
-# Bench if told to
+# Bench if told to (this only works with the nightly toolchain)
 if [ "$DO_BENCH" = true ]
 then
     cargo bench --features="unstable compiler"
 fi
 
+# Build the docs if told to (this only works with the nightly toolchain)
+if [ "$DO_DOCS" = true ]; then
+    RUSTDOCFLAGS="--cfg docsrs" cargo doc --all --features="$FEATURES"
+fi
+
 # Run Integration tests if told so
 if [ -n "$BITCOINVERSION" ]; then
     set -e

src/descriptor/key.rs

@@ -242,13 +242,10 @@ impl fmt::Display for DescriptorPublicKey {
 }
 
 impl DescriptorSecretKey {
-    /// Return the public version of this key, by applying either
-    /// [`SinglePriv::to_public`] or [`DescriptorXKey<bip32::ExtendedPrivKey>::to_public`]
-    /// depending on the type of key.
+    /// Returns the public version of this key.
     ///
-    /// If the key is an "XPrv", the hardened derivation steps will be applied before converting it
-    /// to a public key. See the documentation of [`DescriptorXKey<bip32::ExtendedPrivKey>::to_public`]
-    /// for more details.
+    /// If the key is an "XPrv", the hardened derivation steps will be applied
+    /// before converting it to a public key.
     pub fn to_public<C: Signing>(
         &self,
         secp: &Secp256k1<C>,

src/descriptor/mod.rs

@@ -667,9 +667,9 @@ impl Descriptor<DescriptorPublicKey> {
 
     /// Derive a [`Descriptor`] with a concrete [`bitcoin::PublicKey`] at a given index
     /// Removes all extended pubkeys and wildcards from the descriptor and only leaves
-    /// concrete [`bitcoin::PublicKey`]. All [`crate::XOnlyKey`]s are converted to [`bitcoin::PublicKey`]
-    /// by adding a default(0x02) y-coordinate. For [`crate::descriptor::Tr`] descriptor,
-    /// spend info is also cached.
+    /// concrete [`bitcoin::PublicKey`]. All [`bitcoin::XOnlyPublicKey`]s are converted
+    /// to [`bitcoin::PublicKey`]s by adding a default(0x02) y-coordinate. For [`Tr`]
+    /// descriptor, spend info is also cached.
     ///
     /// # Examples
     ///

src/interpreter/mod.rs

@@ -217,7 +217,7 @@ impl<'txin> Interpreter<'txin> {
     }
 
     /// Verify a signature for a given transaction and prevout information
-    /// This is a low level API, [`Interpreter::iter`] or [`Interpreter::iter_assume_sig`]
+    /// This is a low level API, [`Interpreter::iter`] or [`Interpreter::iter_assume_sigs`]
     /// should satisfy most use-cases.
     /// Returns false if
     /// - the signature verification fails

src/psbt/mod.rs

@@ -553,8 +553,10 @@ pub trait PsbtExt {
     /// # Arguments:
     ///
     /// * `idx`: The input index of psbt to sign
-    /// * `cache`: The [`sighash::SighashCache`] for used to cache/read previously cached computations
+    /// * `cache`: The [`SighashCache`] for used to cache/read previously cached computations
     /// * `tapleaf_hash`: If the output is taproot, compute the sighash for this particular leaf.
+    ///
+    /// [`SighashCache`]: bitcoin::util::sighash::SighashCache
     fn sighash_msg<T: Deref<Target = bitcoin::Transaction>>(
         &self,
         idx: usize,