Merge rust-bitcoin/rust-bitcoin#2798: Standardize rustdoc subheadings

11bb1ff6ff Standardize function doc Safety, Returns and Parameters (jamil.lambert)
df83016c98 Standardize function doc Errors (jamil.lambert)
d219ceb68e Standardize function doc Examples (jamil.lambert)
233a9133d8 Standardize function doc Panics (jamil.lambert)

Pull request description:

  The subheadings in the rustdocs have been standardized according to [./CONTRIBUTING.md](https://github.com/rust-bitcoin/rust-bitcoin/blob/master/CONTRIBUTING.md):
  ```rust
  impl FooBar {
      /// Constructs a `FooBar` from a [`Baz`].
      ///
      /// # Errors
      ///
      /// Returns an error if `Baz` is not ...
      ///
      /// # Panics
      ///
      /// If the `Baz`, converted to a `usize`, is out of bounds.
      pub fn from_baz(baz: Baz) -> Result<Self, Error> {
          ...
      }
  }
  ```

ACKs for top commit:
  apoelstra:
    ACK 11bb1ff6ff
  tcharding:
    ACK 11bb1ff6ff

Tree-SHA512: 163af3cd1cfb47cea3e55eddeaeb6843ff7ec89c57354e3247d6bae85e756b183e8045c2555cfcf87e8c23c1388ff9d7592cfb6a951a37a9ec41d27263e5a2e4

bitcoin/src/bip158.rs

@@ -480,6 +480,7 @@ impl<'a, R: BufRead + ?Sized> BitStreamReader<'a, R> {
     /// Reads nbit bits, returning the bits in a `u64` starting with the rightmost bit.
     ///
     /// # Examples
+    ///
     /// ```
     /// # use bitcoin::bip158::BitStreamReader;
     /// # let data = vec![0xff];

bitcoin/src/blockdata/locktime/absolute.rs

@@ -44,6 +44,7 @@ pub use units::locktime::absolute::{
 /// * [BIP-113 Median time-past as endpoint for lock-time calculations](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki)
 ///
 /// # Examples
+///
 /// ```
 /// # use bitcoin::absolute::{LockTime, LockTime::*};
 /// # let n = LockTime::from_consensus(741521);          // n OP_CHECKLOCKTIMEVERIFY
@@ -60,6 +61,7 @@ pub enum LockTime {
     /// A block height lock time value.
     ///
     /// # Examples
+    ///
     /// ```rust
     /// use bitcoin::absolute::LockTime;
     ///
@@ -72,6 +74,7 @@ pub enum LockTime {
     /// A UNIX timestamp lock time value.
     ///
     /// # Examples
+    ///
     /// ```rust
     /// use bitcoin::absolute::LockTime;
     ///
@@ -129,6 +132,7 @@ impl LockTime {
     /// See [`LOCK_TIME_THRESHOLD`] for definition of a valid height value.
     ///
     /// # Examples
+    ///
     /// ```rust
     /// # use bitcoin::absolute::LockTime;
     /// assert!(LockTime::from_height(741521).is_ok());
@@ -145,6 +149,7 @@ impl LockTime {
     /// See [`LOCK_TIME_THRESHOLD`] for definition of a valid time value.
     ///
     /// # Examples
+    ///
     /// ```rust
     /// # use bitcoin::absolute::LockTime;
     /// assert!(LockTime::from_time(1653195600).is_ok());
@@ -184,6 +189,7 @@ impl LockTime {
     /// `height`/`time` is valid.
     ///
     /// # Examples
+    ///
     /// ```no_run
     /// # use bitcoin::absolute::{LockTime, Height, Time};
     /// // Can be implemented if block chain data is available.

bitcoin/src/blockdata/script/owned.rs

@@ -241,7 +241,7 @@ impl ScriptBuf {
 
     /// Add a single instruction to the script.
     ///
-    /// ## Panics
+    /// # Panics
     ///
     /// The method panics if the instruction is a data push with length greater or equal to
     /// 0x100000000.

bitcoin/src/blockdata/script/push_bytes.rs

@@ -46,7 +46,7 @@ mod primitive {
     impl PushBytes {
         /// Creates `&Self` without checking the length.
         ///
-        /// ## Safety
+        /// # Safety
         ///
         /// The caller is responsible for checking that the length is less than the [`LIMIT`].
         unsafe fn from_slice_unchecked(bytes: &[u8]) -> &Self {
@@ -55,7 +55,7 @@ mod primitive {
 
         /// Creates `&mut Self` without checking the length.
         ///
-        /// ## Safety
+        /// # Safety
         ///
         /// The caller is responsible for checking that the length is less than the [`LIMIT`].
         unsafe fn from_mut_slice_unchecked(bytes: &mut [u8]) -> &mut Self {
@@ -207,7 +207,7 @@ mod primitive {
 
         /// Try pushing a single byte.
         ///
-        /// ## Errors
+        /// # Errors
         ///
         /// This method fails if `self` would exceed the limit.
         #[allow(deprecated)]
@@ -220,7 +220,7 @@ mod primitive {
 
         /// Try appending a slice to `PushBytesBuf`
         ///
-        /// ## Errors
+        /// # Errors
         ///
         /// This method fails if `self` would exceed the limit.
         pub fn extend_from_slice(&mut self, bytes: &[u8]) -> Result<(), PushBytesError> {
@@ -235,7 +235,7 @@ mod primitive {
 
         /// Remove the byte at `index` and return it.
         ///
-        /// ## Panics
+        /// # Panics
         ///
         /// This method panics if `index` is out of bounds.
         #[track_caller]

bitcoin/src/consensus/validation.rs

@@ -21,6 +21,7 @@ use crate::consensus::encode;
 /// [`bitcoinconsensus::VERIFY_ALL`].
 ///
 /// # Parameters
+///
 ///  * `index` - The input index in spending which is spending this transaction.
 ///  * `amount` - The amount this script guards.
 ///  * `spending_tx` - The transaction that attempts to spend the output holding this script.
@@ -38,6 +39,7 @@ pub fn verify_script(
 /// Verifies spend of an input script.
 ///
 /// # Parameters
+///
 ///  * `index` - The input index in spending which is spending this transaction.
 ///  * `amount` - The amount this script guards.
 ///  * `spending_tx` - The transaction that attempts to spend the output holding this script.
@@ -112,6 +114,7 @@ impl Script {
     /// Shorthand for [`Self::verify_with_flags`] with flag [`bitcoinconsensus::VERIFY_ALL`].
     ///
     /// # Parameters
+    ///
     ///  * `index` - The input index in spending which is spending this transaction.
     ///  * `amount` - The amount this script guards.
     ///  * `spending_tx` - The transaction that attempts to spend the output holding this script.
@@ -129,6 +132,7 @@ impl Script {
     /// Verifies spend of an input script.
     ///
     /// # Parameters
+    ///
     ///  * `index` - The input index in spending which is spending this transaction.
     ///  * `amount` - The amount this script guards.
     ///  * `spending_tx` - The transaction that attempts to spend the output holding this script.

bitcoin/src/crypto/key.rs

@@ -710,6 +710,7 @@ pub type UntweakedKeypair = Keypair;
 /// Tweaked BIP-340 key pair
 ///
 /// # Examples
+///
 /// ```
 /// # #[cfg(feature = "rand-std")] {
 /// # use bitcoin::key::{Keypair, TweakedKeypair, TweakedPublicKey};
@@ -746,6 +747,7 @@ pub trait TapTweak {
     ///  * G is the generator point
     ///
     /// # Returns
+    ///
     /// The tweaked key and its parity.
     fn tap_tweak<C: Verification>(
         self,
@@ -775,6 +777,7 @@ impl TapTweak for UntweakedPublicKey {
     ///  * G is the generator point
     ///
     /// # Returns
+    ///
     /// The tweaked key and its parity.
     fn tap_tweak<C: Verification>(
         self,
@@ -806,6 +809,7 @@ impl TapTweak for UntweakedKeypair {
     /// The public key is generated from a private key by multiplying with generator point, Q = qG.
     ///
     /// # Returns
+    ///
     /// The tweaked key and its parity.
     fn tap_tweak<C: Verification>(
         self,

bitcoin/src/merkle_tree/block.rs

@@ -216,6 +216,8 @@ impl PartialMerkleTree {
     /// The `txids` are the transaction hashes of the block and the `matches` is the contains flags
     /// wherever a tx hash should be included in the proof.
     ///
+    /// # Panics
+    ///
     /// Panics when `txids` is empty or when `matches` has a different length
     ///
     /// # Examples

bitcoin/src/merkle_tree/mod.rs

@@ -35,6 +35,7 @@ pub use self::block::{MerkleBlock, MerkleBlockError, PartialMerkleTree};
 /// this method and should not be used again afterwards).
 ///
 /// # Returns
+///
 /// - `None` if `hashes` is empty. The merkle root of an empty tree of hashes is undefined.
 /// - `Some(hash)` if `hashes` contains one element. A single hash is by definition the merkle root.
 /// - `Some(merkle_root)` if length of `hashes` is greater than one.
@@ -53,6 +54,7 @@ where
 /// Calculates the merkle root of an iterator of *hashes*.
 ///
 /// # Returns
+///
 /// - `None` if `hashes` is empty. The merkle root of an empty tree of hashes is undefined.
 /// - `Some(hash)` if `hashes` contains one element. A single hash is by definition the merkle root.
 /// - `Some(merkle_root)` if length of `hashes` is greater than one.

bitcoin/src/psbt/mod.rs

@@ -67,11 +67,11 @@ impl Psbt {
     /// For each PSBT input that contains UTXO information `Ok` is returned containing that information.
     /// The order of returned items is same as the order of inputs.
     ///
-    /// ## Errors
+    /// # Errors
     ///
     /// The function returns error when UTXO information is not present or is invalid.
     ///
-    /// ## Panics
+    /// # Panics
     ///
     /// The function panics if the length of transaction inputs is not equal to the length of PSBT inputs.
     pub fn iter_funding_utxos(&self) -> impl Iterator<Item = Result<&TxOut, Error>> {
@@ -140,7 +140,7 @@ impl Psbt {
 
     /// Extracts the [`Transaction`] from a [`Psbt`] by filling in the available signature information.
     ///
-    /// ## Errors
+    /// # Errors
     ///
     /// [`ExtractTxError`] variants will contain either the [`Psbt`] itself or the [`Transaction`]
     /// that was extracted. These can be extracted from the Errors in order to recover.
@@ -151,7 +151,7 @@ impl Psbt {
 
     /// Extracts the [`Transaction`] from a [`Psbt`] by filling in the available signature information.
     ///
-    /// ## Errors
+    /// # Errors
     ///
     /// See [`extract_tx`].
     ///
@@ -703,7 +703,7 @@ impl Psbt {
     /// 'Fee' being the amount that will be paid for mining a transaction with the current inputs
     /// and outputs i.e., the difference in value of the total inputs and the total outputs.
     ///
-    /// ## Errors
+    /// # Errors
     ///
     /// - [`Error::MissingUtxo`] when UTXO information for any input is not present or is invalid.
     /// - [`Error::NegativeFee`] if calculated value is negative.
@@ -739,6 +739,7 @@ pub trait GetKey {
     /// Attempts to get the private key for `key_request`.
     ///
     /// # Returns
+    ///
     /// - `Some(key)` if the key is found.
     /// - `None` if the key was not found but no error was encountered.
     /// - `Err` if an error was encountered while looking for the key.

bitcoin/src/psbt/raw.rs

@@ -188,6 +188,7 @@ where
     /// Constructs a [`ProprietaryKey`] from a [`Key`].
     ///
     /// # Errors
+    ///
     /// Returns [`Error::InvalidProprietaryKey`] if `key` does not start with `0xFC` byte.
     fn try_from(key: Key) -> Result<Self, Self::Error> {
         if key.type_value != 0xFC {

bitcoin/src/taproot/merkle_branch.rs

@@ -66,6 +66,7 @@ impl TaprootMerkleBranch {
     /// Creates a merkle proof from list of hashes.
     ///
     /// # Errors
+    ///
     /// If inner proof length is more than [`TAPROOT_CONTROL_MAX_NODE_COUNT`] (128).
     #[inline]
     fn from_collection<T: AsRef<[TapNodeHash]> + Into<Vec<TapNodeHash>>>(
@@ -123,6 +124,7 @@ macro_rules! impl_try_from {
             /// Creates a merkle proof from list of hashes.
             ///
             /// # Errors
+            ///
             /// If inner proof length is more than [`TAPROOT_CONTROL_MAX_NODE_COUNT`] (128).
             #[inline]
             fn try_from(v: $from) -> Result<Self, Self::Error> {

bitcoin/src/taproot/mod.rs

@@ -429,8 +429,13 @@ impl TaprootBuilder {
         Ok(TaprootBuilder { branch: vec![Some(node)] })
     }
 
-    /// Adds a leaf script at `depth` to the builder with script version `ver`. Errors if the leaves
+    /// Adds a leaf script at `depth` to the builder with script version `ver`.
-    /// are not provided in DFS walk order. The depth of the root node is 0.
+    ///
+    /// The depth of the root node is 0.
+    ///
+    /// # Errors
+    ///
+    /// Errors if the leaves are not provided in DFS walk order.
     pub fn add_leaf_with_ver(
         self,
         depth: u8,
@@ -441,16 +446,26 @@ impl TaprootBuilder {
         self.insert(leaf, depth)
     }
 
-    /// Adds a leaf script at `depth` to the builder with default script version. Errors if the
+    /// Adds a leaf script at `depth` to the builder with default script version.
-    /// leaves are not provided in DFS walk order. The depth of the root node is 0.
+    ///
+    /// The depth of the root node is 0.
     ///
     /// See [`TaprootBuilder::add_leaf_with_ver`] for adding a leaf with specific version.
+    ///
+    /// # Errors
+    ///
+    /// Errors if the leaves are not provided in DFS walk order.
     pub fn add_leaf(self, depth: u8, script: ScriptBuf) -> Result<Self, TaprootBuilderError> {
         self.add_leaf_with_ver(depth, script, LeafVersion::TapScript)
     }
 
-    /// Adds a hidden/omitted node at `depth` to the builder. Errors if the leaves are not provided
+    /// Adds a hidden/omitted node at `depth` to the builder.
-    /// in DFS walk order. The depth of the root node is 0.
+    ///
+    /// The depth of the root node is 0.
+    ///
+    /// # Errors
+    ///
+    /// Errors if the leaves are not provided in DFS walk order.
     pub fn add_hidden_node(
         self,
         depth: u8,

bitcoin/src/taproot/serialized_signature.rs

@@ -133,7 +133,7 @@ impl<'a> TryFrom<&'a SerializedSignature> for Signature {
 impl SerializedSignature {
     /// Creates `SerializedSignature` from data and length.
     ///
-    /// ## Panics
+    /// # Panics
     ///
     /// If `len` > `MAX_LEN`
     #[inline]

internals/src/macros.rs

@@ -122,7 +122,7 @@ macro_rules! const_assert {
 ///
 /// Note: Paths are not supported (for ex. impl_from_infallible!(Hello<D: std::fmt::Display>).
 ///
-/// ## Examples
+/// # Examples
 ///
 /// ```rust
 /// # use core::fmt::{Display, Debug};

units/src/amount.rs

@@ -21,6 +21,7 @@ use internals::write_err;
 /// A set of denominations in which amounts can be expressed.
 ///
 /// # Examples
+///
 /// ```
 /// # use core::str::FromStr;
 /// # use bitcoin_units::Amount;
@@ -886,7 +887,7 @@ impl Amount {
     /// Convert from a value expressing integer values of bitcoins to an [Amount]
     /// in const context.
     ///
-    /// ## Panics
+    /// # Panics
     ///
     /// The function panics if the argument multiplied by the number of sats
     /// per bitcoin overflows a u64 type.
@@ -939,6 +940,7 @@ impl Amount {
     /// Please be aware of the risk of using floating-point numbers.
     ///
     /// # Examples
+    ///
     /// ```
     /// # use bitcoin_units::amount::{Amount, Denomination};
     /// let amount = Amount::from_sat(100_000);
@@ -1046,12 +1048,20 @@ impl Amount {
 
     /// Unchecked addition.
     ///
-    /// Computes `self + rhs`.  Panics in debug mode, wraps in release mode.
+    /// Computes `self + rhs`.
+    ///
+    /// # Panics
+    ///
+    /// On overflow, panics in debug mode, wraps in release mode.
     pub fn unchecked_add(self, rhs: Amount) -> Amount { Self(self.0 + rhs.0) }
 
     /// Unchecked subtraction.
     ///
-    /// Computes `self - rhs`.  Panics in debug mode, wraps in release mode.
+    /// Computes `self - rhs`.
+    ///
+    /// # Panics
+    ///
+    /// On overflow, panics in debug mode, wraps in release mode.
     pub fn unchecked_sub(self, rhs: Amount) -> Amount { Self(self.0 - rhs.0) }
 
     /// Convert to a signed amount.
@@ -1434,12 +1444,20 @@ impl SignedAmount {
 
     /// Unchecked addition.
     ///
-    /// Computes `self + rhs`.  Panics in debug mode, wraps in release mode.
+    /// Computes `self + rhs`.
+    ///
+    /// # Panics
+    ///
+    /// On overflow, panics in debug mode, wraps in release mode.
     pub fn unchecked_add(self, rhs: SignedAmount) -> SignedAmount { Self(self.0 + rhs.0) }
 
     /// Unchecked subtraction.
     ///
-    /// Computes `self - rhs`.  Panics in debug mode, wraps in release mode.
+    /// Computes `self - rhs`.
+    ///
+    /// # Panics
+    ///
+    /// On overflow, panics in debug mode, wraps in release mode.
     pub fn unchecked_sub(self, rhs: SignedAmount) -> SignedAmount { Self(self.0 - rhs.0) }
 
     /// Subtraction that doesn't allow negative [SignedAmount]s.

units/src/locktime/absolute.rs

@@ -53,6 +53,7 @@ impl Height {
     /// If `n` does not represent a valid block height value.
     ///
     /// # Examples
+    ///
     /// ```rust
     /// use bitcoin_units::locktime::absolute::Height;
     ///
@@ -148,6 +149,7 @@ impl Time {
     /// If `n` does not encode a valid UNIX time stamp.
     ///
     /// # Examples
+    ///
     /// ```rust
     /// use bitcoin_units::locktime::absolute::Time;
     ///