clippy: fix doc_markdown lint

This one has a huge diff, and there's still a ton of work to do to clean
up these docs, but it should be a big improvement.

Author: apoelstra

src/address.rs

@@ -534,7 +534,7 @@ impl Address {
     }
 
     /// Parse the address using the given parameters.
-    /// When using the built-in parameters, you can use [FromStr].
+    /// When using the built-in parameters, you can use [`FromStr`].
     pub fn parse_with_params(
         s: &str,
         params: &'static AddressParams,

src/blind.rs

@@ -39,7 +39,7 @@ pub enum TxOutError {
     UnExpectedNullValue,
     /// Unexpected Null asset
     UnExpectedNullAsset,
-    /// Money should be between 0 and 21_000_000
+    /// Money should be between 0 and `21_000_000`
     MoneyOutofRange,
     /// Zero value explicit txout with non-provably unspendable script
     NonUnspendableZeroValue,
@@ -90,7 +90,7 @@ pub enum VerificationError {
     RangeProofError(usize, secp256k1_zkp::Error),
     /// Missing Range Proof
     RangeProofMissing(usize),
-    /// Verification of SurjectionProof failed
+    /// Verification of `SurjectionProof` failed
     SurjectionProofError(usize, secp256k1_zkp::Error),
     /// Surjection Proof verification error
     SurjectionProofVerificationError(usize),
@@ -165,7 +165,7 @@ pub enum ConfidentialTxOutError {
     NoBlindingKeyInAddress,
     /// Error originated in `secp256k1_zkp`.
     Upstream(secp256k1_zkp::Error),
-    /// General TxOut errors
+    /// General `TxOut` errors
     TxOutError(usize, TxOutError),
     /// Expected Explicit Asset for blinding
     ExpectedExplicitAsset,
@@ -264,7 +264,7 @@ impl TxOutSecrets {
 
     /// Gets the surjection inputs from [`TxOutSecrets`].
     ///
-    /// Returns a tuple (assetid, blind_factor, generator) if the blinds are
+    /// Returns a tuple `(assetid, blind_factor, generator)` if the blinds are
     /// consistent with asset commitment
     /// Otherwise, returns an error
     pub fn surjection_inputs<C: Signing>(&self, secp: &Secp256k1<C>) -> (Generator, Tag, Tweak) {
@@ -327,7 +327,7 @@ impl SurjectionInput {
     }
 
     /// Handy method to convert [`SurjectionInput`] into a surjection target
-    /// that can be used while creating a new [SurjectionProof].
+    /// that can be used while creating a new [`SurjectionProof`].
     ///
     /// Only errors when the input asset is Null.
     pub fn surjection_target<C: Signing>(
@@ -405,8 +405,8 @@ impl Value {
     ///
     /// # Returns:
     ///
-    /// A pair of blinded value, nonce and corresponding proof as ([`Value`], [`Nonce`], [`RangeProof`])
-    /// The nonce here refers to public key corresponding to the input `ephemeral_sk`
+    /// * A pair of blinded value, nonce and corresponding proof as ([`Value`], [`Nonce`], [`RangeProof`])
+    /// * The nonce here refers to public key corresponding to the input `ephemeral_sk`
     pub fn blind<C: Signing>(
         self,
         secp: &Secp256k1<C>,
@@ -424,7 +424,8 @@ impl Value {
         Ok((value_commit, nonce, rangeproof))
     }
 
-    /// Blinds with the given shared_secret(instead of computing it via ECDH)
+    /// Blinds with the given `shared_secret` (instead of computing it via ECDH).
+    ///
     /// This is useful while blinding assets as there is no counter party to provide
     /// the blinding key.
     pub fn blind_with_shared_secret<C: Signing>(
@@ -466,15 +467,15 @@ impl TxOut {
     pub const RANGEPROOF_EXP_SHIFT: i32 = 0;
     /// Rangeproof Minimum private bits
     pub const RANGEPROOF_MIN_PRIV_BITS: u8 = 52;
-    /// Maximum explicit amount in a bitcoin TxOut
+    /// Maximum explicit amount in a bitcoin `TxOut`
     pub const MAX_MONEY: u64 = 21_000_000 * 100_000_000;
 
     /// Creates a new confidential output that is **not** the last one in the transaction.
     /// Provide input secret information by creating [`SurjectionInput`] for each input.
     /// Inputs for issuances must be provided in the followed by inputs for input asset.
     ///
     /// For example, if the second input contains non-null issuance and re-issuance tokens,
-    /// the `spent_utxo_secrets` should be of the form [inp_1, inp_2, inp_2_issue, inp2_reissue,...]
+    /// the `spent_utxo_secrets` should be of the form [`inp_1`, `inp_2`, `inp_2_issue`, `inp2_reissue`,...]
     ///
     /// If the issuance or re-issuance is null, it should not be added to `spent_utxo_secrets`
     ///
@@ -571,7 +572,7 @@ impl TxOut {
         Ok(txout)
     }
 
-    /// Convert a explicit TxOut into a Confidential TxOut.
+    /// Convert a explicit `TxOut` into a Confidential `TxOut`.
     /// The blinding key is provided by the blinder parameter.
     /// The initial value of nonce is ignored and is set to the ECDH pubkey
     /// sampled by the sender.
@@ -653,7 +654,7 @@ impl TxOut {
     ///
     /// Inputs for issuances must be provided in the followed by inputs for input asset.
     /// For example, if the second input contains non-null issuance and re-issuance tokens,
-    /// the `spent_utxo_secrets` should be of the form [inp_1, inp_2, inp_2_issue, inp2_reissue,...]
+    /// the `spent_utxo_secrets` should be of the form [`inp_1`, `inp_2`, `inp_2_issue`, `inp2_reissue`,...]
     /// If the issuance or re-issuance is null, it should not be added to `spent_utxo_secrets`
     ///
     /// # Returns:
@@ -693,7 +694,7 @@ impl TxOut {
         Ok((txout, out_abf, out_vbf, ephemeral_sk))
     }
 
-    /// Similar to [TxOut::new_last_confidential], but allows specifying the asset blinding factor
+    /// Similar to [`TxOut::new_last_confidential`], but allows specifying the asset blinding factor
     /// and the ephemeral key. The value-blinding factor is computed adaptively
     #[allow(clippy::too_many_arguments)]
     pub fn with_secrets_last<R, C>(
@@ -892,7 +893,7 @@ impl TxIn {
     /// Blind issuances for this [`TxIn`]. Asset amount and token amount must be
     /// set in [`AssetIssuance`](crate::AssetIssuance) field for this input
     ///
-    /// Returns (issuance_blinding_factor, issue_blind_sec_key, token_blinding_factor, token_blind_sec_key)
+    /// Returns (`issuance_blinding_factor`, `issue_blind_sec_key`, `token_blinding_factor`, `token_blind_sec_key`)
     pub fn blind_issuances<C: Signing, R: RngCore + CryptoRng>(
         &mut self,
         secp: &Secp256k1<C>,
@@ -937,9 +938,9 @@ impl Transaction {
     /// equation for Confidential transactions holds.
     /// i.e Sum of inputs = Sum of outputs + fees.
     /// And the corresponding surjection/rangeproofs are correct.
-    /// For checking of surjection proofs and amounts, spent_utxos parameter
+    /// For checking of surjection proofs and amounts, `spent_utxos` parameter
     /// should contain information about the prevouts. Note that the order of
-    /// spent_utxos should be consistent with transaction inputs.
+    /// `spent_utxos` should be consistent with transaction inputs.
     /// ## Examples
     ///
     /// ```
@@ -1200,9 +1201,9 @@ pub enum BlindError {
     TooFewBlindingOutputs,
     /// All outputs must be explicit asset/amounts
     MustHaveAllExplicitTxOuts,
-    /// General TxOut errors
+    /// General `TxOut` errors
     ConfidentialTxOutError(ConfidentialTxOutError),
-    /// No Issuances to blind in this TxIn
+    /// No Issuances to blind in this `TxIn`
     NoIssuanceToBlind,
     /// Zero Value Blinding not allowed
     ZeroValueBlindingNotAllowed,
@@ -1278,7 +1279,7 @@ pub trait BlindValueProofs: Sized {
 }
 
 impl BlindValueProofs for RangeProof {
-    /// Outputs a `[RangeProof]` that blinded value_commit
+    /// Outputs a [`RangeProof`] that blinded `value_commit`
     /// corresponds to explicit value
     fn blind_value_proof<C: secp256k1_zkp::Signing, R: RngCore + CryptoRng>(
         rng: &mut R,

src/confidential.rs

@@ -100,7 +100,7 @@ impl Value {
     }
 
     /// Returns the explicit inner value.
-    /// Returns [None] if [Value::is_explicit] returns false.
+    /// Returns [None] if [`Value::is_explicit`] returns false.
     pub fn explicit(&self) -> Option<u64> {
         match *self {
             Value::Explicit(i) => Some(i),
@@ -109,7 +109,7 @@ impl Value {
     }
 
     /// Returns the confidential commitment in case of a confidential value.
-    /// Returns [None] if [Value::is_confidential] returns false.
+    /// Returns [None] if [`Value::is_confidential`] returns false.
     pub fn commitment(&self) -> Option<PedersenCommitment> {
         match *self {
             Value::Confidential(i) => Some(i),
@@ -302,7 +302,7 @@ impl Asset {
     }
 
     /// Returns the explicit inner value.
-    /// Returns [None] if [Asset::is_explicit] returns false.
+    /// Returns [None] if [`Asset::is_explicit`] returns false.
     pub fn explicit(&self) -> Option<AssetId> {
         match *self {
             Asset::Explicit(i) => Some(i),
@@ -311,7 +311,7 @@ impl Asset {
     }
 
     /// Returns the confidential commitment in case of a confidential value.
-    /// Returns [None] if [Asset::is_confidential] returns false.
+    /// Returns [None] if [`Asset::is_confidential`] returns false.
     pub fn commitment(&self) -> Option<Generator> {
         match *self {
             Asset::Confidential(i) => Some(i),
@@ -494,7 +494,7 @@ impl Nonce {
         Self::with_ephemeral_sk(secp, ephemeral_sk, receiver_blinding_pk)
     }
 
-    /// Similar to [Nonce::new_confidential], but with a given `ephemeral_sk`
+    /// Similar to [`Nonce::new_confidential`], but with a given `ephemeral_sk`
     /// instead of sampling it from rng.
     pub fn with_ephemeral_sk<C: Signing>(
         secp: &Secp256k1<C>,
@@ -569,7 +569,7 @@ impl Nonce {
     }
 
     /// Returns the explicit inner value.
-    /// Returns [None] if [Nonce::is_explicit] returns false.
+    /// Returns [None] if [`Nonce::is_explicit`] returns false.
     pub fn explicit(&self) -> Option<[u8; 32]> {
         match *self {
             Nonce::Explicit(i) => Some(i),
@@ -578,7 +578,7 @@ impl Nonce {
     }
 
     /// Returns the confidential commitment in case of a confidential value.
-    /// Returns [None] if [Nonce::is_confidential] returns false.
+    /// Returns [None] if [`Nonce::is_confidential`] returns false.
     pub fn commitment(&self) -> Option<PublicKey> {
         match *self {
             Nonce::Confidential(i) => Some(i),
@@ -740,7 +740,7 @@ impl AssetBlindingFactor {
         self.0
     }
 
-    /// Get a unblinded/zero AssetBlinding factor
+    /// Get a unblinded/zero `AssetBlinding` factor
     pub fn zero() -> Self {
         AssetBlindingFactor(ZERO_TWEAK)
     }
@@ -907,7 +907,7 @@ impl ValueBlindingFactor {
         self.0
     }
 
-    /// Get a unblinded/zero AssetBlinding factor
+    /// Get a unblinded/zero `AssetBlinding` factor
     pub fn zero() -> Self {
         ValueBlindingFactor(ZERO_TWEAK)
     }

src/dynafed.rs

@@ -96,7 +96,7 @@ pub struct FullParams {
 }
 
 impl FullParams {
-    /// Construct a set of FullParams
+    /// Construct a set of `FullParams`
     pub fn new(
         signblockscript: Script,
         signblock_witness_limit: u32,
@@ -131,7 +131,7 @@ impl FullParams {
         crate::fast_merkle_root::fast_merkle_root(&leaves[..])
     }
 
-    /// Calculate the root of this [FullParams].
+    /// Calculate the root of this [`FullParams`].
     pub fn calculate_root(&self) -> sha256::Midstate {
         fn serialize_hash<E: Encodable>(obj: &E) -> sha256d::Hash {
             let mut engine = sha256d::Hash::engine();
@@ -162,7 +162,7 @@ impl FullParams {
         }
     }
 
-    /// Format for [fmt::Debug].
+    /// Format for [`fmt::Debug`].
     fn fmt_debug(&self, f: &mut fmt::Formatter, name: &'static str) -> fmt::Result {
         let mut s = f.debug_struct(name);
         s.field("signblockscript", &HexBytes(&self.signblockscript[..]));
@@ -253,7 +253,7 @@ impl fmt::Debug for Params {
 }
 
 impl Params {
-    /// Check whether this is [Params::Null].
+    /// Check whether this is [`Params::Null`].
     pub fn is_null(&self) -> bool {
         match *self {
             Params::Null => true,
@@ -262,7 +262,7 @@ impl Params {
         }
     }
 
-    /// Check whether this is [Params::Compact].
+    /// Check whether this is [`Params::Compact`].
     pub fn is_compact(&self) -> bool {
         match *self {
             Params::Null => false,
@@ -271,7 +271,7 @@ impl Params {
         }
     }
 
-    /// Check whether this is [Params::Full].
+    /// Check whether this is [`Params::Full`].
     pub fn is_full(&self) -> bool {
         match *self {
             Params::Null => false,
@@ -280,7 +280,7 @@ impl Params {
         }
     }
 
-    /// Get the signblockscript. Is [None] for [Params::Null] params.
+    /// Get the signblockscript. Is [None] for [`Params::Null`] params.
     pub fn signblockscript(&self) -> Option<&Script> {
         match *self {
             Params::Null => None,
@@ -289,7 +289,7 @@ impl Params {
         }
     }
 
-    /// Get the signblock_witness_limit. Is [None] for [Params::Null] params.
+    /// Get the `signblock_witness_limit`. Is [None] for [`Params::Null`] params.
     pub fn signblock_witness_limit(&self) -> Option<u32> {
         match *self {
             Params::Null => None,
@@ -298,7 +298,7 @@ impl Params {
         }
     }
 
-    /// Get the fedpeg_program. Is [None] for non-[Params::Full] params.
+    /// Get the `fedpeg_program`. Is [None] for non-[`Params::Full`] params.
     pub fn fedpeg_program(&self) -> Option<&bitcoin::ScriptBuf> {
         match *self {
             Params::Null => None,
@@ -307,7 +307,7 @@ impl Params {
         }
     }
 
-    /// Get the fedpegscript. Is [None] for non-[Params::Full] params.
+    /// Get the fedpegscript. Is [None] for non-[`Params::Full`] params.
     pub fn fedpegscript(&self) -> Option<&Vec<u8>> {
         match *self {
             Params::Null => None,
@@ -316,7 +316,7 @@ impl Params {
         }
     }
 
-    /// Get the extension_space. Is [None] for non-[Params::Full] params.
+    /// Get the `extension_space`. Is [None] for non-[`Params::Full`] params.
     pub fn extension_space(&self) -> Option<&Vec<Vec<u8>>> {
         match *self {
             Params::Null => None,
@@ -325,7 +325,7 @@ impl Params {
         }
     }
 
-    /// Get the elided_root. Is [None] for non-[Params::Compact] params.
+    /// Get the `elided_root`. Is [None] for non-[`Params::Compact`] params.
     pub fn elided_root(&self) -> Option<&sha256::Midstate> {
         match *self {
             Params::Null => None,

src/encode.rs

@@ -59,7 +59,7 @@ pub enum Error {
     HexError(crate::hex::Error),
     /// Got a time-based locktime when expecting a height-based one, or vice-versa
     BadLockTime(crate::LockTime),
-    /// VarInt was encoded in a non-minimal way.
+    /// `VarInt` was encoded in a non-minimal way.
     NonMinimalVarInt,
 }
 

src/error.rs

@@ -2,7 +2,7 @@
 
 pub use crate::parse::ParseIntError;
 
-/// Impls std::error::Error for the specified type with appropriate attributes, possibly returning
+/// Impls `std::error::Error` for the specified type with appropriate attributes, possibly returning
 /// source.
 macro_rules! impl_std_error {
     // No source available

src/hash_types.rs

@@ -15,7 +15,7 @@
 //! File defines types for hashes used throughout the library.
 //!
 //! These types are needed in order
-//! to avoid mixing data of the same hash format (like SHA256d) but of different meaning
+//! to avoid mixing data of the same hash format (like `SHA256d`) but of different meaning
 //! (transaction id, block hash etc).
 
 use crate::hashes::{hash160, hash_newtype, sha256, sha256d, Hash};

src/internal_macros.rs

@@ -211,7 +211,7 @@ macro_rules! serde_string_impl {
     };
 }
 
-/// A combination of serde_struct_impl and serde_string_impl where string is
+/// A combination of `serde_struct_impl` and `serde_string_impl` where string is
 /// used for human-readable serialization and struct is used for
 /// non-human-readable serialization.
 macro_rules! serde_struct_human_string_impl {