Merge #730: docs: fix new clippy lint about excessively long initial …

…line

05dace0 docs: fix new clippy lint about excessively long initial line (Andrew Poelstra)

Pull request description:

  Also does a few miscellaneous fixes that I noticed while fixing the lint.

ACKs for top commit:
  tcharding:
    ACK 05dace0
  sanket1729:
    ACK 05dace0

Tree-SHA512: d01fa4da51da2042a4f480096ca316b0d2a49955809f471779b060e9da00eac7051d49c3fb64c42b0791cb778a1cc01558e9f373c5020b8efccb88cb9c046884

src/miniscript/context.rs

@@ -152,7 +152,9 @@ impl fmt::Display for ScriptContextError {
     }
 }
 
-/// The ScriptContext for Miniscript. Additional type information associated with
+/// The ScriptContext for Miniscript.
+///
+/// Additional type information associated with
 /// miniscript that is used for carrying out checks that dependent on the
 /// context under which the script is used.
 /// For example, disallowing uncompressed keys in Segwit context

src/miniscript/satisfy.rs

@@ -26,6 +26,7 @@ use crate::{
 /// Type alias for 32 byte Preimage.
 pub type Preimage32 = [u8; 32];
 /// Trait describing a lookup table for signatures, hash preimages, etc.
+///
 /// Every method has a default implementation that simply returns `None`
 /// on every query. Users are expected to override the methods that they
 /// have data for.
@@ -58,7 +59,8 @@ pub trait Satisfier<Pk: MiniscriptKey + ToPublicKey> {
     /// Given a raw `Pkh`, lookup corresponding [`bitcoin::secp256k1::XOnlyPublicKey`]
     fn lookup_raw_pkh_x_only_pk(&self, _: &hash160::Hash) -> Option<XOnlyPublicKey> { None }
 
-    /// Given a keyhash, look up the EC signature and the associated key
+    /// Given a keyhash, look up the EC signature and the associated key.
+    ///
     /// Even if signatures for public key Hashes are not available, the users
     /// can use this map to provide pkh -> pk mapping which can be useful
     /// for dissatisfying pkh.
@@ -69,7 +71,8 @@ pub trait Satisfier<Pk: MiniscriptKey + ToPublicKey> {
         None
     }
 
-    /// Given a keyhash, look up the schnorr signature and the associated key
+    /// Given a keyhash, look up the schnorr signature and the associated key.
+    ///
     /// Even if signatures for public key Hashes are not available, the users
     /// can use this map to provide pkh -> pk mapping which can be useful
     /// for dissatisfying pkh.

src/miniscript/types/correctness.rs

@@ -72,10 +72,11 @@ impl Input {
     }
 }
 
-/// Structure representing the type properties of a fragment which are
-/// relevant to completeness (are all expected branches actually accessible,
-/// given some valid witness) and soundness (is it possible to satisfy the
-/// Script without satisfying one of the Miniscript branches).
+/// Soundness and completeness type properties of a fragment.
+///
+/// Completeness is the property that a valid witness actually exists for all
+/// branches, which an honest user can produce. Soundness is the property
+/// that no branch can be satisfied _without_ an honest user.
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)]
 pub struct Correctness {
     /// The base type

src/miniscript/types/malleability.rs

@@ -3,7 +3,9 @@
 //! Malleability-related Type properties
 
 /// Whether the fragment has a dissatisfaction, and if so, whether
-/// it is unique. Affects both correctness and malleability-freeness,
+/// it is unique.
+///
+/// Affects both correctness and malleability-freeness,
 /// since we assume 3rd parties are able to produce dissatisfactions
 /// for all fragments.
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)]
@@ -12,11 +14,15 @@ pub enum Dissat {
     /// input.
     None,
     /// Fragment has a unique dissatisfaction, which is always available,
-    /// and will push 0 given this dissatisfaction as input. The combination
+    /// and will push 0 given this dissatisfaction as input.
+    ///
+    /// The combination
     /// of `Dissat::Unique` and `Input::Zero` implies that a fragment is
     /// impossible to satisfy (is a `0` or equivalent).
     Unique,
-    /// No assumptions may be made about dissatisfying this fragment. This
+    /// No assumptions may be made about dissatisfying this fragment.
+    ///
+    /// This
     /// does not necessarily mean that there are multiple dissatisfactions;
     /// there may be none, or none that are always available (e.g. for a
     /// `pk_h` the key preimage may not be available).
@@ -52,8 +58,9 @@ pub struct Malleability {
     /// Properties of dissatisfying inputs
     pub dissat: Dissat,
     /// `true` if satisfactions cannot be created by any 3rd party
-    /// who has not yet seen a satisfaction. (Hash preimages and
-    /// signature checks are safe; timelocks are not.) Affects
+    /// who has not yet seen a satisfaction.
+    ///
+    /// Hash preimages and signature checks are safe; timelocks are not. Affects
     /// malleability.
     pub safe: bool,
     /// Whether a non-malleable satisfaction is guaranteed to exist for
@@ -69,7 +76,8 @@ impl Malleability {
     pub const FALSE: Self =
         Malleability { dissat: Dissat::Unique, safe: true, non_malleable: true };
 
-    /// Check whether the `self` is a subtype of `other` argument .
+    /// Check whether the `self` is a subtype of `other` argument.
+    ///
     /// This checks whether the argument `other` has attributes which are present
     /// in the given `Type`. This returns `true` on same arguments
     /// `a.is_subtype(a)` is `true`.

src/miniscript/types/mod.rs

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: CC0-1.0
 
 //! Miniscript Types
+//!
 //! Contains structures representing Miniscript types and utility functions
 //! Contains all the type checking rules for correctness and malleability
 //! Implemented as per rules on bitcoin.sipa.be/miniscript

src/plan.rs

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: CC0-1.0
 
-//! A spending plan or *plan* for short is a representation of a particular spending path on a
-//! descriptor. This allows us to analayze a choice of spending path without producing any
+//! A spending plan (or *plan*) is a representation of a particular spending path on a
+//! descriptor.
+//!
+//! This allows us to analayze a choice of spending path without producing any
 //! signatures or other witness data for it.
 //!
 //! To make a plan you provide the descriptor with "assets" like which keys you are able to use, hash
@@ -67,7 +69,9 @@ pub trait AssetProvider<Pk: MiniscriptKey> {
     }
 
     /// Given a keyhash, look up the EC signature and the associated key.
+    ///
     /// Returns the key if a signature is found.
+    ///
     /// Even if signatures for public key Hashes are not available, the users
     /// can use this map to provide pkh -> pk mapping which can be useful
     /// for dissatisfying pkh.
@@ -76,7 +80,9 @@ pub trait AssetProvider<Pk: MiniscriptKey> {
     }
 
     /// Given a keyhash, look up the schnorr signature and the associated key.
+    ///
     /// Returns the key and sig len if a signature is found.
+    ///
     /// Even if signatures for public key Hashes are not available, the users
     /// can use this map to provide pkh -> pk mapping which can be useful
     /// for dissatisfying pkh.
@@ -211,7 +217,9 @@ where
     fn check_after(&self, l: absolute::LockTime) -> bool { Satisfier::check_after(self, l) }
 }
 
-/// Representation of a particular spending path on a descriptor. Contains the witness template
+/// Representation of a particular spending path on a descriptor.
+///
+/// Contains the witness template
 /// and the timelocks needed for satisfying the plan.
 /// Calling `plan` on a Descriptor will return this structure,
 /// containing the cheapest spending path possible (considering the `Assets` given)
@@ -499,7 +507,9 @@ impl TaprootAvailableLeaves {
 /// The Assets we can use to satisfy a particular spending path
 #[derive(Debug, Default)]
 pub struct Assets {
-    /// Keys the user can sign for, and how. A pair `(fingerprint, derivation_path)` is
+    /// Keys the user can sign for, and how.
+    ///
+    /// A pair `(fingerprint, derivation_path)` is
     /// provided, meaning that the user can sign using the key with `fingerprint`,
     /// derived with either `derivation_path` or a derivation path that extends `derivation_path`
     /// by exactly one child number. For example, if the derivation path `m/0/1` is provided, the

src/psbt/finalizer.rs

@@ -1,7 +1,7 @@
 // Written in 2020 by Sanket Kanjalkar <[email protected]>
 // SPDX-License-Identifier: CC0-1.0
 
-//! # Partially-Signed Bitcoin Transactions
+//! Partially-Signed Bitcoin Transactions
 //!
 //! This module implements the Finalizer and Extractor roles defined in
 //! BIP 174, PSBT, described at
@@ -298,7 +298,8 @@ fn get_descriptor(psbt: &Psbt, index: usize) -> Result<Descriptor<PublicKey>, In
 }
 
 /// Interprets all psbt inputs and checks whether the
-/// script is correctly interpreted according to the context
+/// script is correctly interpreted according to the context.
+///
 /// The psbt must have included final script sig and final witness.
 /// In other words, this checks whether the finalized psbt interprets
 /// correctly
@@ -351,7 +352,9 @@ fn interpreter_inp_check<C: secp256k1::Verification, T: Borrow<TxOut>>(
     Ok(())
 }
 
-/// Finalize the psbt. This function takes in a mutable reference to psbt
+/// Finalize the psbt.
+///
+/// This function takes in a mutable reference to psbt
 /// and populates the final_witness and final_scriptsig
 /// of the psbt assuming all of the inputs are miniscript as per BIP174.
 /// If any of the inputs is not miniscript, this returns a parsing error

src/psbt/mod.rs

@@ -235,8 +235,9 @@ impl From<bitcoin::key::FromSliceError> for InputError {
     fn from(e: bitcoin::key::FromSliceError) -> InputError { InputError::KeyErr(e) }
 }
 
-/// Psbt satisfier for at inputs at a particular index
-/// Takes in &psbt because multiple inputs will share
+/// Psbt satisfier for at inputs at a particular index.
+///
+/// Holds a `&psbt` because multiple inputs may share
 /// the same psbt structure
 /// All operations on this structure will panic if index
 /// is more than number of inputs in pbst
@@ -510,8 +511,10 @@ pub trait PsbtExt {
     ) -> Result<Psbt, (Psbt, Error)>;
 
     /// Psbt extractor as defined in BIP174 that takes in a psbt reference
-    /// and outputs a extracted bitcoin::Transaction
-    /// Also does the interpreter sanity check
+    /// and outputs a extracted [`bitcoin::Transaction`].
+    ///
+    /// Also does the interpreter sanity check.
+    ///
     /// Will error if the final ScriptSig or final Witness are missing
     /// or the interpreter check fails.
     fn extract<C: secp256k1::Verification>(