Merge rust-bitcoin/rust-bitcoin#4383: rustdocs: Make headings consistent

c4d9c1b9f8 Use a consistent rustdoc heading level of H1 `#` (Jamil Lambert) 6325a7cdea Change rustdoc heading level of references (Jamil Lambert) f22e997587 Use parameters instead of arguments in rustdocs (Jamil Lambert) e2c7be6d2f Fix typo (Jamil Lambert) Pull request description: In the rustdocs both `# Parameters` and `# Arguments` are used to mean the same thing. In a previous PR #2792 it was decided to go with Parameters everywhere. Since then there have been a few additions of "Arguments" into the rustdocs. There is also a mix in the usage of `#`, `##` or `###` for headings. Noticed here https://github.com/rust-bitcoin/rust-bitcoin/pull/2792#issuecomment-2125775974. - Fix a typo found when looking into this. - Change all occurances to use `# Parameters` in rustdocs. - Change all heading levels to H1 `#` - Change all subheading levels to H3 `###` to make the small difference in the rendered font size noticable Closes #4380 ACKs for top commit: apoelstra: ACK c4d9c1b9f8e59bf795812c42bd1eee68d97b9bbd; successfully ran local tests Tree-SHA512: c8cc77ccf7e2003dd2dd1d309268624576e3bf390cd8ac61b0a7bb1141ca05377c83627576b0b7ff258b8e51c2d255097a4363fbdd1b368db7d32ac32ece58a1
2025-04-24 16:44:17 +00:00 · 2025-04-24 16:44:17 +00:00 · 04f706f6bd
parent 4ad6e80683 c4d9c1b9f8
commit 04f706f6bd
16 changed files with 37 additions and 39 deletions
--- a/bitcoin/examples/ecdsa-psbt.rs
+++ b/bitcoin/examples/ecdsa-psbt.rs
@ -5,7 +5,7 @@
 //!
 //! You can verify the workflow using `bitcoind` and `bitcoin-cli`.
 //!
-//! ## Example Setup
+//! # Example Setup
 //!
 //! 1. Start Bitcoin Core in Regtest mode, for example:
 //!
--- a/bitcoin/src/address/mod.rs
+++ b/bitcoin/src/address/mod.rs
@ -313,7 +313,7 @@ pub enum AddressData {
 internals::transparent_newtype! {
    /// A Bitcoin address.
    ///
-    /// ### Parsing addresses
+    /// # Parsing addresses
    ///
    /// When parsing string as an address, one has to pay attention to the network, on which the parsed
    /// address is supposed to be valid. For the purpose of this validation, `Address` has
@ -386,7 +386,7 @@ internals::transparent_newtype! {
    /// assert_eq!(format!("{:?}", address), "132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM");
    /// ```
    ///
-    /// ### Relevant BIPs
+    /// # Relevant BIPs
    ///
    /// * [BIP13 - Address Format for pay-to-script-hash](https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki)
    /// * [BIP16 - Pay to Script Hash](https://github.com/bitcoin/bips/blob/master/bip-0016.mediawiki)
--- a/bitcoin/src/bip158.rs
+++ b/bitcoin/src/bip158.rs
@ -11,7 +11,7 @@
 //! is an alternative to Bloom filters, as used in BIP 37, that minimizes filter
 //! size by using Golomb-Rice coding for compression.
 //!
-//! ### Relevant BIPS
+//! # Relevant BIPS
 //!
 //! * [BIP 157 - Client Side Block Filtering](https://github.com/bitcoin/bips/blob/master/bip-0157.mediawiki)
 //! * [BIP 158 - Compact Block Filters for Light Clients](https://github.com/bitcoin/bips/blob/master/bip-0158.mediawiki)
--- a/bitcoin/src/blockdata/script/mod.rs
+++ b/bitcoin/src/blockdata/script/mod.rs
@ -31,7 +31,7 @@
 //! and forcing them to be larger would waste memory and, in case of Bitcoin script, even some
 //! performance (forcing allocations).
 //!
-//! ## `Script` vs `ScriptBuf` vs `Builder`
+//! # `Script` vs `ScriptBuf` vs `Builder`
 //!
 //! These are the most important types in this module and they are quite similar, so it may seem
 //! confusing what the differences are. `Script` is an unsized type much like `str` or `Path` are
--- a/bitcoin/src/consensus/encode.rs
+++ b/bitcoin/src/consensus/encode.rs
@ -284,7 +284,7 @@ pub trait Decodable: Sized {
    /// vector of a limited size, calling this function directly might be marginally faster (due to
    /// avoiding extra checks).
    ///
-    /// ### Rules for trait implementations
+    /// # Rules for trait implementations
    ///
    /// * Simple types that have a fixed size (own and member fields), don't have to overwrite
    ///   this method, or be concern with it.
--- a/chacha20_poly1305/src/lib.rs
+++ b/chacha20_poly1305/src/lib.rs
@ -75,7 +75,7 @@ impl ChaCha20Poly1305 {

    /// Encrypt content in place and return the Poly1305 16-byte authentication tag.
    ///
-    /// # Arguments
+    /// # Parameters
    ///
    /// - `content` - Plaintext to be encrypted in place.
    /// - `aad`     - Optional metadata covered by the authentication tag.
@ -110,7 +110,7 @@ impl ChaCha20Poly1305 {

    /// Decrypt the ciphertext in place if authentication tag is correct.
    ///
-    /// # Arguments
+    /// # Parameters
    ///
    /// - `content` - Ciphertext to be decrypted in place.
    /// - `tag`     - 16-byte authentication tag.
--- a/hashes/src/internal_macros.rs
+++ b/hashes/src/internal_macros.rs
@ -4,8 +4,9 @@

 /// Adds trait impls to the type called `Hash` in the current scope.
 ///
-/// Implpements various conversion traits as well as the [`crate::Hash`] trait.
-/// Arguments:
+/// Implements various conversion traits as well as the [`crate::Hash`] trait.
+///
+/// # Parameters
 ///
 /// * `$bits` - number of bits this hash type has
 /// * `$reverse` - `bool`  - `true` if the hash type should be displayed backwards, `false`
@ -55,7 +56,7 @@ pub(crate) use hash_trait_impls;
 /// The created type has a single field and will have all standard derives as well as an
 /// implementation of [`crate::Hash`].
 ///
-/// Arguments:
+/// # Parameters
 ///
 /// * `$bits` - the number of bits of the hash type
 /// * `$reverse` - `true` if the hash should be displayed backwards, `false` otherwise
--- a/hashes/src/macros.rs
+++ b/hashes/src/macros.rs
@ -218,7 +218,7 @@ macro_rules! impl_debug_only_for_newtype {
 /// * `Borrow<[u8; $len]>`
 /// * `Borrow<[u8]>`
 ///
-/// ## Parameters
+/// # Parameters
 ///
 /// * `ty` - The bytelike type to implement the traits on.
 /// * `$len` - The number of bytes this type has.
@ -262,7 +262,7 @@ macro_rules! impl_bytelike_traits {
 ///
 /// (See also [`hex-conservative::fmt_hex_exact`].)
 ///
-/// ## Parameters
+/// # Parameters
 ///
 /// * `ty` - The bytelike type to implement the traits on.
 /// * `$len` - The number of bytes this type has.
--- a/primitives/src/block.rs
+++ b/primitives/src/block.rs
@ -47,7 +47,7 @@ pub trait Validation: sealed::Validation + Sync + Send + Sized + Unpin {
 ///
 /// [wiki-block]: https://en.bitcoin.it/wiki/Block
 ///
-/// ### Bitcoin Core References
+/// # Bitcoin Core References
 ///
 /// * [CBlock definition](https://github.com/bitcoin/bitcoin/blob/345457b542b6a980ccfbc868af0970a6f91d1b82/src/primitives/block.h#L62)
 #[cfg(feature = "alloc")]
@ -167,7 +167,7 @@ mod sealed {
 ///
 /// [Merkle tree]: https://en.wikipedia.org/wiki/Merkle_tree
 ///
-/// ### Bitcoin Core References
+/// # Bitcoin Core References
 ///
 /// * [CBlockHeader definition](https://github.com/bitcoin/bitcoin/blob/345457b542b6a980ccfbc868af0970a6f91d1b82/src/primitives/block.h#L20)
 #[derive(Copy, PartialEq, Eq, Clone, PartialOrd, Ord, Hash)]
@ -261,7 +261,7 @@ impl From<&Header> for BlockHash {
 ///
 /// > When a block nVersion does not have top bits 001, it is treated as if all bits are 0 for the purposes of deployments.
 ///
-/// ### Relevant BIPs
+/// # Relevant BIPs
 ///
 /// * [BIP9 - Version bits with timeout and delay](https://github.com/bitcoin/bips/blob/master/bip-0009.mediawiki) (current usage)
 /// * [BIP34 - Block v2, Height in Coinbase](https://github.com/bitcoin/bips/blob/master/bip-0034.mediawiki)
--- a/primitives/src/locktime/absolute.rs
+++ b/primitives/src/locktime/absolute.rs
@ -24,7 +24,7 @@ pub use units::locktime::absolute::{ConversionError, Height, ParseHeightError, P
 /// Used for transaction lock time (`nLockTime` in Bitcoin Core and [`Transaction::lock_time`]
 /// in this library) and also for the argument to opcode `OP_CHECKLOCKTIMEVERIFY`.
 ///
-/// ### Note on ordering
+/// # Note on ordering
 ///
 /// Locktimes may be height- or time-based, and these metrics are incommensurate; there is no total
 /// ordering on locktimes. In order to compare locktimes, instead of using `<` or `>` we provide the
@ -34,7 +34,7 @@ pub use units::locktime::absolute::{ConversionError, Height, ParseHeightError, P
 /// it easy to store transactions in sorted data structures, and use the locktime's 32-bit integer
 /// consensus encoding to order it.
 ///
-/// ### Relevant BIPs
+/// # Relevant BIPs
 ///
 /// * [BIP-65 OP_CHECKLOCKTIMEVERIFY](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki)
 /// * [BIP-113 Median time-past as endpoint for lock-time calculations](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki)
--- a/primitives/src/locktime/relative.rs
+++ b/primitives/src/locktime/relative.rs
@ -20,13 +20,13 @@ pub use units::locktime::relative::{Height, Time, TimeOverflowError};
 /// Used for sequence numbers (`nSequence` in Bitcoin Core and [`TxIn::sequence`]
 /// in this library) and also for the argument to opcode `OP_CHECKSEQUENCEVERIFY`.
 ///
-/// ### Note on ordering
+/// # Note on ordering
 ///
 /// Locktimes may be height- or time-based, and these metrics are incommensurate; there is no total
 /// ordering on locktimes. In order to compare locktimes, instead of using `<` or `>` we provide the
 /// [`LockTime::is_satisfied_by`] API.
 ///
-/// ### Relevant BIPs
+/// # Relevant BIPs
 ///
 /// * [BIP 68 Relative lock-time using consensus-enforced sequence numbers](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki)
 /// * [BIP 112 CHECKSEQUENCEVERIFY](https://github.com/bitcoin/bips/blob/master/bip-0112.mediawiki)
--- a/primitives/src/script/borrowed.rs
+++ b/primitives/src/script/borrowed.rs
@ -19,7 +19,7 @@ internals::transparent_newtype! {
    /// form `&Script`. It is always encoded as a series of bytes representing the opcodes and data
    /// pushes.
    ///
-    /// ## Validity
+    /// # Validity
    ///
    /// `Script` does not have any validity invariants - it's essentially just a marked slice of
    /// bytes. This is similar to [`Path`](std::path::Path) vs [`OsStr`](std::ffi::OsStr) where they
@ -30,7 +30,7 @@ internals::transparent_newtype! {
    /// allowed to be in a transaction (outputs just become unspendable) and there even are such
    /// transactions in the chain. Thus we must allow such scripts to be placed in the transaction.
    ///
-    /// ## Slicing safety
+    /// # Slicing safety
    ///
    /// Slicing is similar to how `str` works: some ranges may be incorrect and indexing by
    /// `usize` is not supported. However, as opposed to `std`, we have no way of checking
@ -44,15 +44,12 @@ internals::transparent_newtype! {
    /// It is recommended to use `.instructions()` method to get an iterator over script
    /// instructions and work with that instead.
    ///
-    /// ## Memory safety
+    /// # Memory safety
    ///
    /// The type is `#[repr(transparent)]` for internal purposes only!
    /// No consumer crate may rely on the representation of the struct!
    ///
-    /// ## References
-    ///
-    ///
-    /// ### Bitcoin Core References
+    /// # Bitcoin Core References
    ///
    /// * [CScript definition](https://github.com/bitcoin/bitcoin/blob/d492dc1cdaabdc52b0766bf4cba4bd73178325d0/src/script/script.h#L410)
    ///
--- a/primitives/src/sequence.rs
+++ b/primitives/src/sequence.rs
@ -81,7 +81,7 @@ impl Sequence {
    /// Instead of this method please consider using `!enables_absolute_lock_time` because it
    /// is equivalent and improves readability for those not steeped in Bitcoin folklore.
    ///
-    /// ## Historical note
+    /// # Historical note
    ///
    /// The term 'final' is an archaic Bitcoin term, it may have come about because the sequence
    /// number in the original Bitcoin code was intended to be incremented in order to replace a
--- a/primitives/src/transaction.rs
+++ b/primitives/src/transaction.rs
@ -48,11 +48,11 @@ use crate::witness::Witness;
 ///
 /// [wiki-transaction]: https://en.bitcoin.it/wiki/Transaction
 ///
-/// ### Bitcoin Core References
+/// # Bitcoin Core References
 ///
 /// * [CTtransaction definition](https://github.com/bitcoin/bitcoin/blob/345457b542b6a980ccfbc868af0970a6f91d1b82/src/primitives/transaction.h#L279)
 ///
-/// ### Serialization notes
+/// # Serialization notes
 ///
 /// If any inputs have nonempty witnesses, the entire transaction is serialized
 /// in the post-BIP141 SegWit format which includes a list of witnesses. If all
@ -83,7 +83,7 @@ use crate::witness::Witness;
 /// We therefore deviate from the spec by always using the SegWit witness encoding
 /// for 0-input transactions, which results in unambiguously parseable transactions.
 ///
-/// ### A note on ordering
+/// # A note on ordering
 ///
 /// This type implements `Ord`, even though it contains a locktime, which is not
 /// itself `Ord`. This was done to simplify applications that may need to hold
@ -103,7 +103,7 @@ pub struct Transaction {
    pub version: Version,
    /// Block height or timestamp. Transaction cannot be included in a block until this height/time.
    ///
-    /// ### Relevant BIPs
+    /// # Relevant BIPs
    ///
    /// * [BIP-65 OP_CHECKLOCKTIMEVERIFY](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki)
    /// * [BIP-113 Median time-past as endpoint for lock-time calculations](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki)
@ -310,7 +310,7 @@ fn hash_transaction(tx: &Transaction, uses_segwit_serialization: bool) -> sha256
 /// that it spends and set of scripts that satisfy its spending
 /// conditions.
 ///
-/// ### Bitcoin Core References
+/// # Bitcoin Core References
 ///
 /// * [CTxIn definition](https://github.com/bitcoin/bitcoin/blob/345457b542b6a980ccfbc868af0970a6f91d1b82/src/primitives/transaction.h#L65)
 #[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)]
@ -354,7 +354,7 @@ impl TxIn {
 ///
 /// An output that is not yet spent by an input is called Unspent Transaction Output ("UTXO").
 ///
-/// ### Bitcoin Core References
+/// # Bitcoin Core References
 ///
 /// * [CTxOut definition](https://github.com/bitcoin/bitcoin/blob/345457b542b6a980ccfbc868af0970a6f91d1b82/src/primitives/transaction.h#L148)
 #[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)]
@ -370,7 +370,7 @@ pub struct TxOut {

 /// A reference to a transaction output.
 ///
-/// ### Bitcoin Core References
+/// # Bitcoin Core References
 ///
 /// * [COutPoint definition](https://github.com/bitcoin/bitcoin/blob/345457b542b6a980ccfbc868af0970a6f91d1b82/src/primitives/transaction.h#L26)
 #[derive(Copy, Clone, Debug, Eq, Hash, PartialEq, PartialOrd, Ord)]
--- a/units/src/parse.rs
+++ b/units/src/parse.rs
@ -139,7 +139,7 @@ fn int<T: Integer, S: AsRef<str> + Into<InputString>>(s: S) -> Result<T, ParseIn
 /// * `TryFrom<Box<str>>`
 /// * `TryFrom<String>`
 ///
-/// # Arguments
+/// # Parameters
 ///
 /// * `to` - the type converted to e.g., `impl From<&str> for $to`.
 /// * `err` - the error type returned by `$inner_fn` (implies returned by `FromStr` and `TryFrom`).
@ -204,7 +204,7 @@ macro_rules! impl_parse_str_from_int_infallible {
 /// * `TryFrom<Box<str>>`
 /// * `TryFrom<String>`
 ///
-/// # Arguments
+/// # Parameters
 ///
 /// * `to` - the type converted to e.g., `impl From<&str> for $to`.
 /// * `err` - the error type returned by `$inner_fn` (implies returned by `FromStr` and `TryFrom`).
--- a/units/src/result.rs
+++ b/units/src/result.rs
@ -22,7 +22,7 @@ use crate::{Amount, FeeRate, SignedAmount, Weight};
 ///
 /// The `NumOpResult` type provides protection against overflow and div-by-zero.
 ///
-/// ## Overflow protection
+/// ### Overflow protection
 ///
 /// ```
 /// # use bitcoin_units::{amount, Amount};
@ -48,7 +48,7 @@ use crate::{Amount, FeeRate, SignedAmount, Weight};
 /// # Ok::<_, amount::OutOfRangeError>(())
 /// ```
 ///
-/// ## Divide-by-zero (overflow in `Div` or `Rem`)
+/// ### Divide-by-zero (overflow in `Div` or `Rem`)
 ///
 /// In some instances one may wish to differentiate div-by-zero from overflow.
 ///