Enable usage of -D rustdoc::broken-intra-doc-links

Currently we have a bunch of broken links in our docs. Fix all the
broken links an add `-D rustdoc::broken-intra-doc-links` to the docs
build in CI.

There are a few other improvements scattered through this PR, I tried to
find a balance between scope creep and obvious errors in the diff.

Author: tcharding

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

@@ -154,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,