Merge #507: Enable -D rustdoc::broken-intra-doc-links

ebaa31b Enable usage of -D rustdoc::broken-intra-doc-links (Tobin C. Harding)
16b6c76 Improve docs on enumerate_policy_tree (Tobin C. Harding)
90dc766 Do trivial cleanup to main lib docs (Tobin C. Harding)

Pull request description:

  Make an effort to do some docs improvements without touching the whole codebase.

  - Patch 1: Trivial, because I can't help myself.
  - Patch 2: Clean up docs on a private method in preparation for duplicating in public docs
  - Patch 3: Fix broken links and enable `-D rustdoc::broken-intra-doc-links` in CI

  I'm in no way across this codebase, there may be other problems with docs that show up in this PR but the PR is an attempt at improving the docs without going too wild - both for my sanity and that of reviewers.

ACKs for top commit:
  apoelstra:
    ACK ebaa31b

Tree-SHA512: 6982f615fe6565f0defca30a4d4f4e077f9bcf446c1ed5f86cb15986c6b1d6f95a34cbd0d9b9c6096ccb932767aa71f99011931f612cc33c69709c79857679a0

Author: apoelstra

contrib/test.sh

@@ -92,7 +92,7 @@ fi
 
 # Build the docs if told to (this only works with the nightly toolchain)
 if [ "$DO_DOCS" = true ]; then
-    RUSTDOCFLAGS="--cfg docsrs" cargo doc --features="$FEATURES"
+    RUSTDOCFLAGS="--cfg docsrs" cargo +nightly rustdoc --features="$FEATURES" -- -D rustdoc::broken-intra-doc-links
 fi
 
 exit 0

src/descriptor/key.rs

@@ -600,7 +600,7 @@ impl DescriptorPublicKey {
     }
 
     #[deprecated(note = "use at_derivation_index instead")]
-    /// Deprecated name of [`at_derivation_index`].
+    /// Deprecated name for [`Self::at_derivation_index`].
     pub fn derive(self, index: u32) -> Result<DefiniteDescriptorKey, ConversionError> {
         self.at_derivation_index(index)
     }

src/descriptor/mod.rs

@@ -537,7 +537,7 @@ impl Descriptor<DescriptorPublicKey> {
     }
 
     #[deprecated(note = "use at_derivation_index instead")]
-    /// Deprecated name for [`at_derivation_index`].
+    /// Deprecated name for [`Self::at_derivation_index`].
     pub fn derive(&self, index: u32) -> Result<Descriptor<DefiniteDescriptorKey>, ConversionError> {
         self.at_derivation_index(index)
     }

src/interpreter/stack.rs

@@ -15,8 +15,9 @@ use crate::miniscript::context::SigType;
 use crate::prelude::*;
 
 /// Definition of Stack Element of the Stack used for interpretation of Miniscript.
-/// All stack elements with vec![] go to Dissatisfied and vec![1] are marked to Satisfied.
-/// Others are directly pushed as witness
+///
+/// All stack elements with `vec![]` go to `Element::Dissatisfied` and `vec![1]` are marked to
+/// `Element::Satisfied`. Others are directly pushed as witness.
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)]
 pub enum Element<'txin> {
     /// Result of a satisfied Miniscript fragment

src/lib.rs

@@ -3,7 +3,6 @@
 
 //! Miniscript and Output Descriptors
 //!
-//! # Introduction
 //! ## Bitcoin Script
 //!
 //! In Bitcoin, spending policies are defined and enforced by means of a
@@ -35,7 +34,7 @@
 //! While spending policies in Bitcoin are entirely defined by Script; there
 //! are multiple ways of embedding these Scripts in transaction outputs; for
 //! example, P2SH or Segwit v0. These different embeddings are expressed by
-//! *Output Descriptors*, [which are described here](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md)
+//! *Output Descriptors*, [which are described here](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md).
 //!
 //! # Examples
 //!
@@ -51,7 +50,7 @@
 //!     )))\
 //!     ").unwrap();
 //!
-//! // Derive the P2SH address
+//! // Derive the P2SH address.
 //! assert_eq!(
 //!     desc.address(bitcoin::Network::Bitcoin).unwrap().to_string(),
 //!     "3CJxbQBfWAe1ZkKiGQNEYrioV73ZwvBWns"
@@ -62,7 +61,7 @@
 //! // elements in Wsh scripts or they contain a combination of timelock and heightlock.
 //! assert!(desc.sanity_check().is_ok());
 //!
-//! // Estimate the satisfaction cost
+//! // Estimate the satisfaction cost.
 //! assert_eq!(desc.max_satisfaction_weight().unwrap(), 293);
 //! ```
 //!
@@ -155,19 +154,20 @@ pub trait MiniscriptKey: Clone + Eq + Ord + fmt::Debug + fmt::Display + hash::Ha
     /// in BIP389 multipath descriptors.
     fn num_der_paths(&self) -> usize;
 
-    /// The associated [`sha256::Hash`] for this [`MiniscriptKey`],
-    /// used in the hash256 fragment.
+    /// The associated [`bitcoin::hashes::sha256::Hash`] for this [`MiniscriptKey`], used in the
+    /// sha256 fragment.
     type Sha256: Clone + Eq + Ord + fmt::Display + fmt::Debug + hash::Hash;
 
-    /// The associated [`hash256::Hash`] for this [`MiniscriptKey`],
-    /// used in the hash256 fragment.
+    /// The associated [`miniscript::hash256::Hash`] for this [`MiniscriptKey`], used in the
+    /// hash256 fragment.
     type Hash256: Clone + Eq + Ord + fmt::Display + fmt::Debug + hash::Hash;
-    /// The associated [`ripedmd160::Hash`] for this [`MiniscriptKey`] type.
-    /// used in the ripemd160 fragment
+
+    /// The associated [`bitcoin::hashes::ripemd160::Hash`] for this [`MiniscriptKey`] type, used
+    /// in the ripemd160 fragment.
     type Ripemd160: Clone + Eq + Ord + fmt::Display + fmt::Debug + hash::Hash;
 
-    /// The associated [`hash160::Hash`] for this [`MiniscriptKey`] type.
-    /// used in the hash160 fragment
+    /// The associated [`bitcoin::hashes::hash160::Hash`] for this [`MiniscriptKey`] type, used in
+    /// the hash160 fragment.
     type Hash160: Clone + Eq + Ord + fmt::Display + fmt::Debug + hash::Hash;
 }
 

src/miniscript/decode.rs

@@ -24,6 +24,9 @@ use crate::miniscript::ScriptContext;
 use crate::prelude::*;
 use crate::{bitcoin, hash256, Error, Miniscript, MiniscriptKey, ToPublicKey};
 
+#[cfg(doc)]
+use crate::Descriptor;
+
 fn return_none<T>(_: usize) -> Option<T> {
     None
 }
@@ -112,14 +115,14 @@ enum NonTerm {
     // could be or_i or tern
     EndIfElse,
 }
-/// All AST elements
-/// This variant is the inner Miniscript variant that allows the user to bypass
-/// some of the miniscript rules. You should *never* construct Terminal directly.
-/// This is only exposed to external user to allow matching on the [`crate::Miniscript`]
+/// All AST elements.
+///
+/// This variant is the inner Miniscript variant that allows the user to bypass some of the
+/// miniscript rules. You should *never* construct `Terminal` directly. This is only exposed to
+/// external users to allow matching on the [`Miniscript`].
 ///
-/// The average user should always use the [`crate::Descriptor`] APIs. Advanced users
-/// who want deal with Miniscript ASTs should use the [`crate::Miniscript`] APIs.
-#[allow(broken_intra_doc_links)]
+/// The average user should always use the [`Descriptor`] APIs. Advanced users who want deal
+/// with Miniscript ASTs should use the [`Miniscript`] APIs.
 #[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum Terminal<Pk: MiniscriptKey, Ctx: ScriptContext> {
     /// `1`
@@ -160,38 +163,38 @@ pub enum Terminal<Pk: MiniscriptKey, Ctx: ScriptContext> {
     Check(Arc<Miniscript<Pk, Ctx>>),
     /// `DUP IF [V] ENDIF`
     DupIf(Arc<Miniscript<Pk, Ctx>>),
-    /// [T] VERIFY
+    /// `[T] VERIFY`
     Verify(Arc<Miniscript<Pk, Ctx>>),
-    /// SIZE 0NOTEQUAL IF [Fn] ENDIF
+    /// `SIZE 0NOTEQUAL IF [Fn] ENDIF`
     NonZero(Arc<Miniscript<Pk, Ctx>>),
-    /// [X] 0NOTEQUAL
+    /// `[X] 0NOTEQUAL`
     ZeroNotEqual(Arc<Miniscript<Pk, Ctx>>),
     // Conjunctions
-    /// [V] [T]/[V]/[F]/[Kt]
+    /// `[V] [T]/[V]/[F]/[Kt]`
     AndV(Arc<Miniscript<Pk, Ctx>>, Arc<Miniscript<Pk, Ctx>>),
-    /// [E] [W] BOOLAND
+    /// `[E] [W] BOOLAND`
     AndB(Arc<Miniscript<Pk, Ctx>>, Arc<Miniscript<Pk, Ctx>>),
-    /// [various] NOTIF [various] ELSE [various] ENDIF
+    /// `[various] NOTIF [various] ELSE [various] ENDIF`
     AndOr(
         Arc<Miniscript<Pk, Ctx>>,
         Arc<Miniscript<Pk, Ctx>>,
         Arc<Miniscript<Pk, Ctx>>,
     ),
     // Disjunctions
-    /// [E] [W] BOOLOR
+    /// `[E] [W] BOOLOR`
     OrB(Arc<Miniscript<Pk, Ctx>>, Arc<Miniscript<Pk, Ctx>>),
-    /// [E] IFDUP NOTIF [T]/[E] ENDIF
+    /// `[E] IFDUP NOTIF [T]/[E] ENDIF`
     OrD(Arc<Miniscript<Pk, Ctx>>, Arc<Miniscript<Pk, Ctx>>),
-    /// [E] NOTIF [V] ENDIF
+    /// `[E] NOTIF [V] ENDIF`
     OrC(Arc<Miniscript<Pk, Ctx>>, Arc<Miniscript<Pk, Ctx>>),
-    /// IF [various] ELSE [various] ENDIF
+    /// `IF [various] ELSE [various] ENDIF`
     OrI(Arc<Miniscript<Pk, Ctx>>, Arc<Miniscript<Pk, Ctx>>),
     // Thresholds
-    /// [E] ([W] ADD)* k EQUAL
+    /// `[E] ([W] ADD)* k EQUAL`
     Thresh(usize, Vec<Arc<Miniscript<Pk, Ctx>>>),
-    /// k (<key>)* n CHECKMULTISIG
+    /// `k (<key>)* n CHECKMULTISIG`
     Multi(usize, Vec<Pk>),
-    /// <key> CHECKSIG (<key> CHECKSIGADD)*(n-1) k NUMEQUAL
+    /// `<key> CHECKSIG (<key> CHECKSIGADD)*(n-1) k NUMEQUAL`
     MultiA(usize, Vec<Pk>),
 }
 

src/policy/concrete.rs

@@ -29,6 +29,9 @@ use crate::miniscript::types::extra_props::TimelockInfo;
 use crate::prelude::*;
 use crate::{errstr, Error, ForEachKey, MiniscriptKey, Translator};
 
+#[cfg(all(doc, not(feature = "compiler")))]
+use crate::Descriptor;
+
 /// Maximum TapLeafs allowed in a compiled TapTree
 #[cfg(feature = "compiler")]
 const MAX_COMPILATION_LEAVES: usize = 1024;
@@ -207,18 +210,18 @@ pub enum PolicyError {
     DuplicatePubKeys,
 }
 
-/// Descriptor context for [`Policy`] compilation into a [`Descriptor`]
+/// Descriptor context for [`Policy`] compilation into a [`Descriptor`].
 pub enum DescriptorCtx<Pk> {
-    /// [Bare][`Descriptor::Bare`]
+    /// See docs for [`Descriptor::Bare`].
     Bare,
-    /// [Sh][`Descriptor::Sh`]
+    /// See docs for [`Descriptor::Sh`].
     Sh,
-    /// [Wsh][`Descriptor::Wsh`]
+    /// See docs for [`Descriptor::Wsh`].
     Wsh,
-    /// Sh-wrapped [Wsh][`Descriptor::Wsh`]
+    /// See docs for [`Descriptor::Wsh`].
     ShWsh,
-    /// [Tr][`Descriptor::Tr`] where the Option<Pk> corresponds to the internal_key if no internal
-    /// key can be inferred from the given policy
+    /// [`Descriptor::Tr`] where the `Option<Pk>` corresponds to the internal key if no
+    /// internal key can be inferred from the given policy.
     Tr(Option<Pk>),
 }
 
@@ -364,7 +367,7 @@ impl<Pk: MiniscriptKey> Policy<Pk> {
         }
     }
 
-    /// Compile the [`Policy`] into a [`Tr`][`Descriptor::Tr`] Descriptor.
+    /// Compile the [`Policy`] into a [`Descriptor::Tr`].
     ///
     /// ### TapTree compilation
     ///
@@ -417,20 +420,26 @@ impl<Pk: MiniscriptKey> Policy<Pk> {
         }
     }
 
-    /// Compile the [`Policy`] into a [`Tr`][`Descriptor::Tr`] Descriptor, with policy-enumeration
-    /// by [`Policy::enumerate_policy_tree`].
+    /// Compiles the [`Policy`] into a [`Descriptor::Tr`].
     ///
     /// ### TapTree compilation
     ///
-    /// The policy tree constructed by root-level disjunctions over [`Or`][`Policy::Or`] and
-    /// [`Thresh`][`Policy::Threshold`](k, ..n..) which is flattened into a vector (with respective
-    /// probabilities derived from odds) of policies.
-    /// For example, the policy `thresh(1,or(pk(A),pk(B)),and(or(pk(C),pk(D)),pk(E)))` gives the vector
+    /// The policy tree constructed by root-level disjunctions over [`Policy::Or`] and
+    /// [`Policy::Threshold`] (k, ..n..) which is flattened into a vector (with respective
+    /// probabilities derived from odds) of policies. For example, the policy
+    /// `thresh(1,or(pk(A),pk(B)),and(or(pk(C),pk(D)),pk(E)))` gives the vector
     /// `[pk(A),pk(B),and(or(pk(C),pk(D)),pk(E)))]`.
     ///
     /// ### Policy enumeration
     ///
-    /// Refer to [`Policy::enumerate_policy_tree`] for the current strategy implemented.
+    /// Generates a root-level disjunctive tree over the given policy tree.
+    ///
+    /// Uses a fixed-point algorithm to enumerate the disjunctions until exhaustive root-level
+    /// enumeration or limits exceed. For a given [`Policy`], we maintain an [ordered
+    /// set](`BTreeSet`) of `(prob, policy)` (ordered by probability) to maintain the list of
+    /// enumerated sub-policies whose disjunction is isomorphic to initial policy (*invariant*).
+    ///
+    /// [`Policy`]: crate::policy::concrete::Policy
     #[cfg(feature = "compiler")]
     pub fn compile_tr_private_experimental(
         &self,
@@ -537,12 +546,14 @@ impl<Pk: MiniscriptKey> PolicyArc<Pk> {
         }
     }
 
-    /// Generates a root-level disjunctive tree over the given policy tree, by using fixed-point
-    /// algorithm to enumerate the disjunctions until exhaustive root-level enumeration or limits
-    /// exceed.
-    /// For a given [policy][`Policy`], we maintain an [ordered set][`BTreeSet`] of `(prob, policy)`
-    /// (ordered by probability) to maintain the list of enumerated sub-policies whose disjunction
-    /// is isomorphic to initial policy (*invariant*).
+    /// Generates a root-level disjunctive tree over the given policy tree.
+    ///
+    /// Uses a fixed-point algorithm to enumerate the disjunctions until exhaustive root-level
+    /// enumeration or limits exceed. For a given [`Policy`], we maintain an [ordered
+    /// set](`BTreeSet`) of `(prob, policy)` (ordered by probability) to maintain the list of
+    /// enumerated sub-policies whose disjunction is isomorphic to initial policy (*invariant*).
+    ///
+    /// [`Policy`]: crate::policy::concrete::Policy
     #[cfg(feature = "compiler")]
     fn enumerate_policy_tree(self, prob: f64) -> Vec<(f64, Arc<Self>)> {
         let mut tapleaf_prob_vec = BTreeSet::<(Reverse<OrdF64>, Arc<Self>)>::new();