From e2c7be6d2f5e017a67ed919e9f75176ca539a339 Mon Sep 17 00:00:00 2001 From: Jamil Lambert Date: Tue, 22 Apr 2025 10:39:43 +0100 Subject: [PATCH 1/4] Fix typo --- hashes/src/internal_macros.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hashes/src/internal_macros.rs b/hashes/src/internal_macros.rs index 19945b46c..20d029e33 100644 --- a/hashes/src/internal_macros.rs +++ b/hashes/src/internal_macros.rs @@ -4,7 +4,7 @@ /// Adds trait impls to the type called `Hash` in the current scope. /// -/// Implpements various conversion traits as well as the [`crate::Hash`] trait. +/// Implements various conversion traits as well as the [`crate::Hash`] trait. /// Arguments: /// /// * `$bits` - number of bits this hash type has From f22e9975872e1d23a2b5b7b036060a6f387a19ea Mon Sep 17 00:00:00 2001 From: Jamil Lambert Date: Tue, 22 Apr 2025 10:43:13 +0100 Subject: [PATCH 2/4] Use parameters instead of arguments in rustdocs The rustdocs use both `# Parameters` and `# Arguments` to mean the same thing. Change all of them to `# Parameters` to be consistent. --- chacha20_poly1305/src/lib.rs | 4 ++-- hashes/src/internal_macros.rs | 5 +++-- units/src/parse.rs | 4 ++-- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/chacha20_poly1305/src/lib.rs b/chacha20_poly1305/src/lib.rs index 0deea843d..7777e0935 100644 --- 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. diff --git a/hashes/src/internal_macros.rs b/hashes/src/internal_macros.rs index 20d029e33..d325d13b7 100644 --- a/hashes/src/internal_macros.rs +++ b/hashes/src/internal_macros.rs @@ -5,7 +5,8 @@ /// Adds trait impls to the type called `Hash` in the current scope. /// /// Implements various conversion traits as well as the [`crate::Hash`] trait. -/// Arguments: +/// +/// # 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 diff --git a/units/src/parse.rs b/units/src/parse.rs index 9c0a6ca6b..502a4a1e7 100644 --- a/units/src/parse.rs +++ b/units/src/parse.rs @@ -139,7 +139,7 @@ fn int + Into>(s: S) -> Result>` /// * `TryFrom` /// -/// # 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>` /// * `TryFrom` /// -/// # 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`). From 6325a7cdea7cdf7025d6ba41af28a542ab6b51b1 Mon Sep 17 00:00:00 2001 From: Jamil Lambert Date: Tue, 22 Apr 2025 12:55:48 +0100 Subject: [PATCH 3/4] Change rustdoc heading level of references `Bitcoin Core References` used H3 `###` in rustdocs, and one occurrence had another `References` heading above it. Change them to be H1 `#` like other headings. Remove the redundant `References` heading. NB. there are no other occurrences of `# References` in this crate. --- primitives/src/block.rs | 4 ++-- primitives/src/script/borrowed.rs | 5 +---- primitives/src/transaction.rs | 8 ++++---- 3 files changed, 7 insertions(+), 10 deletions(-) diff --git a/primitives/src/block.rs b/primitives/src/block.rs index f746f4dbc..6ac3655d2 100644 --- 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)] diff --git a/primitives/src/script/borrowed.rs b/primitives/src/script/borrowed.rs index 8e0ea3f5a..87a97c15b 100644 --- a/primitives/src/script/borrowed.rs +++ b/primitives/src/script/borrowed.rs @@ -49,10 +49,7 @@ internals::transparent_newtype! { /// 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) /// diff --git a/primitives/src/transaction.rs b/primitives/src/transaction.rs index 53cd51a4f..640bc8200 100644 --- a/primitives/src/transaction.rs +++ b/primitives/src/transaction.rs @@ -48,7 +48,7 @@ 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) /// @@ -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)] From c4d9c1b9f8e59bf795812c42bd1eee68d97b9bbd Mon Sep 17 00:00:00 2001 From: Jamil Lambert Date: Tue, 22 Apr 2025 13:06:32 +0100 Subject: [PATCH 4/4] Use a consistent rustdoc heading level of H1 `#` There was and inconsistent usage of `#`, `##` and `###` in rustdoc headings. The difference in the rendered rustdocs is a minimal font size change. Change all headings to be H1 `#`. Change all subheadings to be `###` to have a noticeable difference in font size in the rendered docs. --- bitcoin/examples/ecdsa-psbt.rs | 2 +- bitcoin/src/address/mod.rs | 4 ++-- bitcoin/src/bip158.rs | 2 +- bitcoin/src/blockdata/script/mod.rs | 2 +- bitcoin/src/consensus/encode.rs | 2 +- hashes/src/macros.rs | 4 ++-- primitives/src/block.rs | 2 +- primitives/src/locktime/absolute.rs | 4 ++-- primitives/src/locktime/relative.rs | 4 ++-- primitives/src/script/borrowed.rs | 6 +++--- primitives/src/sequence.rs | 2 +- primitives/src/transaction.rs | 6 +++--- units/src/result.rs | 4 ++-- 13 files changed, 22 insertions(+), 22 deletions(-) diff --git a/bitcoin/examples/ecdsa-psbt.rs b/bitcoin/examples/ecdsa-psbt.rs index e6bbaf1e6..5aa05ea97 100644 --- 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: //! diff --git a/bitcoin/src/address/mod.rs b/bitcoin/src/address/mod.rs index ebaf248ac..0a1981245 100644 --- 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) diff --git a/bitcoin/src/bip158.rs b/bitcoin/src/bip158.rs index 67b55ef9e..512d57001 100644 --- 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) diff --git a/bitcoin/src/blockdata/script/mod.rs b/bitcoin/src/blockdata/script/mod.rs index 1bd2bddf3..dccfe6727 100644 --- 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 diff --git a/bitcoin/src/consensus/encode.rs b/bitcoin/src/consensus/encode.rs index c2a751a0f..3620c1867 100644 --- 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. diff --git a/hashes/src/macros.rs b/hashes/src/macros.rs index 2c9aa1bcf..162af9a03 100644 --- 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. diff --git a/primitives/src/block.rs b/primitives/src/block.rs index 6ac3655d2..e022d3f2b 100644 --- a/primitives/src/block.rs +++ b/primitives/src/block.rs @@ -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) diff --git a/primitives/src/locktime/absolute.rs b/primitives/src/locktime/absolute.rs index ad03f5102..d6434ed83 100644 --- 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) diff --git a/primitives/src/locktime/relative.rs b/primitives/src/locktime/relative.rs index 7a08d2296..59dfdd0d6 100644 --- 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) diff --git a/primitives/src/script/borrowed.rs b/primitives/src/script/borrowed.rs index 87a97c15b..59e4585fa 100644 --- 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,7 +44,7 @@ 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! diff --git a/primitives/src/sequence.rs b/primitives/src/sequence.rs index 75e956941..df291b7ee 100644 --- 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 diff --git a/primitives/src/transaction.rs b/primitives/src/transaction.rs index 640bc8200..28eadde17 100644 --- a/primitives/src/transaction.rs +++ b/primitives/src/transaction.rs @@ -52,7 +52,7 @@ use crate::witness::Witness; /// /// * [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) diff --git a/units/src/result.rs b/units/src/result.rs index bf57d30fc..3d1ee003d 100644 --- 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. ///