From 4a9f74b55c4f9a55b8e5eeb83e72a7d535078d82 Mon Sep 17 00:00:00 2001 From: "Jamil Lambert, PhD" Date: Tue, 28 May 2024 12:08:44 +0100 Subject: [PATCH 1/3] fix missing fullstops in bitcoin rustdoc Added missing fullstops to the rustdoc titles for everything on the main page of the bitcoin crate --- bitcoin/src/bip152.rs | 2 +- bitcoin/src/bip158.rs | 4 ++-- bitcoin/src/blockdata/witness.rs | 2 +- bitcoin/src/crypto/key.rs | 6 +++--- bitcoin/src/sign_message.rs | 2 +- hashes/src/sha256t.rs | 2 +- units/src/amount.rs | 4 ++-- 7 files changed, 11 insertions(+), 11 deletions(-) diff --git a/bitcoin/src/bip152.rs b/bitcoin/src/bip152.rs index ce5b7844b..ab809751b 100644 --- a/bitcoin/src/bip152.rs +++ b/bitcoin/src/bip152.rs @@ -1,6 +1,6 @@ // SPDX-License-Identifier: CC0-1.0 -//! BIP152 Compact Blocks +//! BIP152 Compact Blocks. //! //! Implementation of compact blocks data structure and algorithms. diff --git a/bitcoin/src/bip158.rs b/bitcoin/src/bip158.rs index 4d0bc4d38..7e54b810c 100644 --- a/bitcoin/src/bip158.rs +++ b/bitcoin/src/bip158.rs @@ -57,9 +57,9 @@ const P: u8 = 19; const M: u64 = 784931; hashes::hash_newtype! { - /// Filter hash, as defined in BIP-157 + /// Filter hash, as defined in BIP-157. pub struct FilterHash(sha256d::Hash); - /// Filter header, as defined in BIP-157 + /// Filter header, as defined in BIP-157. pub struct FilterHeader(sha256d::Hash); } diff --git a/bitcoin/src/blockdata/witness.rs b/bitcoin/src/blockdata/witness.rs index c118f5767..a1d9b40d6 100644 --- a/bitcoin/src/blockdata/witness.rs +++ b/bitcoin/src/blockdata/witness.rs @@ -1,6 +1,6 @@ // SPDX-License-Identifier: CC0-1.0 -//! Witness +//! A witness. //! //! This module contains the [`Witness`] struct and related methods to operate on it diff --git a/bitcoin/src/crypto/key.rs b/bitcoin/src/crypto/key.rs index 60bbe5c74..d1492b830 100644 --- a/bitcoin/src/crypto/key.rs +++ b/bitcoin/src/crypto/key.rs @@ -28,7 +28,7 @@ pub use secp256k1::{constants, Keypair, Parity, Secp256k1, Verification, XOnlyPu #[cfg(feature = "rand-std")] pub use secp256k1::rand; -/// A Bitcoin ECDSA public key +/// A Bitcoin ECDSA public key. #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct PublicKey { /// Whether this public key should be serialized as compressed @@ -269,7 +269,7 @@ impl From<&PublicKey> for PubkeyHash { fn from(key: &PublicKey) -> PubkeyHash { key.pubkey_hash() } } -/// An always-compressed Bitcoin ECDSA public key +/// An always-compressed Bitcoin ECDSA public key. #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct CompressedPublicKey(pub secp256k1::PublicKey); @@ -393,7 +393,7 @@ impl From<&CompressedPublicKey> for WPubkeyHash { fn from(key: &CompressedPublicKey) -> Self { key.wpubkey_hash() } } -/// A Bitcoin ECDSA private key +/// A Bitcoin ECDSA private key. #[derive(Debug, Copy, Clone, PartialEq, Eq)] pub struct PrivateKey { /// Whether this private key should be serialized as compressed diff --git a/bitcoin/src/sign_message.rs b/bitcoin/src/sign_message.rs index b373e4523..9f7bb524d 100644 --- a/bitcoin/src/sign_message.rs +++ b/bitcoin/src/sign_message.rs @@ -1,6 +1,6 @@ // SPDX-License-Identifier: CC0-1.0 -//! Signature +//! A signature. //! //! This module provides signature related functions including secp256k1 signature recovery when //! library is used with the `secp-recovery` feature. diff --git a/hashes/src/sha256t.rs b/hashes/src/sha256t.rs index 375154e97..0560bd3db 100644 --- a/hashes/src/sha256t.rs +++ b/hashes/src/sha256t.rs @@ -141,7 +141,7 @@ macro_rules! sha256t_hash_newtype_tag { ($vis:vis, $tag:ident, $name:expr, $(#[$($attr:meta)*])*) => { #[doc = "The tag used for [`"] #[doc = $name] - #[doc = "`]\n\n"] + #[doc = "`].\n\n"] $(#[$($attr)*])* #[derive(Copy, Clone, PartialEq, Eq, Default, PartialOrd, Ord, Hash)] $vis struct $tag; diff --git a/units/src/amount.rs b/units/src/amount.rs index 98e8216c8..40b3a6c7a 100644 --- a/units/src/amount.rs +++ b/units/src/amount.rs @@ -835,7 +835,7 @@ fn fmt_satoshi_in( Ok(()) } -/// Amount +/// An amount. /// /// The [Amount] type can be used to express Bitcoin amounts that support /// arithmetic and conversion to various denominations. @@ -1234,7 +1234,7 @@ enum DisplayStyle { DynamicDenomination, } -/// SignedAmount +/// A signed amount. /// /// The [SignedAmount] type can be used to express Bitcoin amounts that support /// arithmetic and conversion to various denominations. From bac30d3e6e0af349dbab6fc5f45090d89b51ef74 Mon Sep 17 00:00:00 2001 From: "Jamil Lambert, PhD" Date: Tue, 4 Jun 2024 17:12:13 +0100 Subject: [PATCH 2/3] fix rustdocs in bip152 Added backticks on links and changed to third person on function rustdocs --- bitcoin/src/bip152.rs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/bitcoin/src/bip152.rs b/bitcoin/src/bip152.rs index ab809751b..b20fb8b22 100644 --- a/bitcoin/src/bip152.rs +++ b/bitcoin/src/bip152.rs @@ -49,7 +49,7 @@ impl std::error::Error for Error { } } -/// A [PrefilledTransaction] structure is used in [HeaderAndShortIds] to +/// A [`PrefilledTransaction`] structure is used in [`HeaderAndShortIds`] to /// provide a list of a few transactions explicitly. #[derive(PartialEq, Eq, Clone, Debug, PartialOrd, Ord, Hash)] pub struct PrefilledTransaction { @@ -97,7 +97,7 @@ impl_array_newtype!(ShortId, u8, 6); impl_array_newtype_stringify!(ShortId, 6); impl ShortId { - /// Calculate the SipHash24 keys used to calculate short IDs. + /// Calculates the SipHash24 keys used to calculate short IDs. pub fn calculate_siphash_keys(header: &block::Header, nonce: u64) -> (u64, u64) { // 1. single-SHA256 hashing the block header with the nonce appended (in little-endian) let h = { @@ -115,7 +115,7 @@ impl ShortId { ) } - /// Calculate the short ID with the given (w)txid and using the provided SipHash keys. + /// Calculates the short ID with the given (w)txid and using the provided SipHash keys. pub fn with_siphash_keys>(txid: &T, siphash_keys: (u64, u64)) -> ShortId { // 2. Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) // set to the first two little-endian 64-bit integers from the above hash, respectively. @@ -142,7 +142,7 @@ impl Decodable for ShortId { } } -/// A [HeaderAndShortIds] structure is used to relay a block header, the short +/// A [`HeaderAndShortIds`] structure is used to relay a block header, the short /// transactions IDs used for matching already-available transactions, and a /// select few transactions which we expect a peer may be missing. #[derive(PartialEq, Eq, Clone, Debug, PartialOrd, Ord, Hash)] @@ -161,7 +161,7 @@ pub struct HeaderAndShortIds { impl_consensus_encoding!(HeaderAndShortIds, header, nonce, short_ids, prefilled_txs); impl HeaderAndShortIds { - /// Create a new [HeaderAndShortIds] from a full block. + /// Creates a new [`HeaderAndShortIds`] from a full block. /// /// The version number must be either 1 or 2. /// @@ -242,7 +242,7 @@ impl HeaderAndShortIds { } } -/// A [BlockTransactionsRequest] structure is used to list transaction indexes +/// A [`BlockTransactionsRequest`] structure is used to list transaction indexes /// in a block being requested. #[derive(PartialEq, Eq, Clone, Debug, PartialOrd, Ord, Hash)] pub struct BlockTransactionsRequest { @@ -335,7 +335,7 @@ impl error::Error for TxIndexOutOfRangeError { fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { None } } -/// A [BlockTransactions] structure is used to provide some of the transactions +/// A [`BlockTransactions`] structure is used to provide some of the transactions /// in a block, as requested. #[derive(PartialEq, Eq, Clone, Debug, PartialOrd, Ord, Hash)] pub struct BlockTransactions { @@ -347,8 +347,8 @@ pub struct BlockTransactions { impl_consensus_encoding!(BlockTransactions, block_hash, transactions); impl BlockTransactions { - /// Construct a [BlockTransactions] from a [BlockTransactionsRequest] and - /// the corresponding full [Block] by providing all requested transactions. + /// Constructs a [`BlockTransactions`] from a [`BlockTransactionsRequest`] and + /// the corresponding full [`Block`] by providing all requested transactions. pub fn from_request( request: &BlockTransactionsRequest, block: &Block, From 5e7a638b4d7e2a0d87030046564f95e88b1a97c3 Mon Sep 17 00:00:00 2001 From: "Jamil Lambert, PhD" Date: Tue, 4 Jun 2024 17:31:44 +0100 Subject: [PATCH 3/3] fix crypto rustdocs Fixed the rustdocs for some of the functions to be in third person, and small gramatical changes. --- bitcoin/src/crypto/key.rs | 74 +++++++++++++++++------------------ bitcoin/src/crypto/taproot.rs | 8 ++-- 2 files changed, 41 insertions(+), 41 deletions(-) diff --git a/bitcoin/src/crypto/key.rs b/bitcoin/src/crypto/key.rs index d1492b830..01a7f7f18 100644 --- a/bitcoin/src/crypto/key.rs +++ b/bitcoin/src/crypto/key.rs @@ -31,20 +31,20 @@ pub use secp256k1::rand; /// A Bitcoin ECDSA public key. #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct PublicKey { - /// Whether this public key should be serialized as compressed + /// Whether this public key should be serialized as compressed. pub compressed: bool, - /// The actual ECDSA key + /// The actual ECDSA key. pub inner: secp256k1::PublicKey, } impl PublicKey { - /// Constructs compressed ECDSA public key from the provided generic Secp256k1 public key + /// Constructs compressed ECDSA public key from the provided generic Secp256k1 public key. pub fn new(key: impl Into) -> PublicKey { PublicKey { compressed: true, inner: key.into() } } /// Constructs uncompressed (legacy) ECDSA public key from the provided generic Secp256k1 - /// public key + /// public key. pub fn new_uncompressed(key: impl Into) -> PublicKey { PublicKey { compressed: false, inner: key.into() } } @@ -57,7 +57,7 @@ impl PublicKey { } } - /// Returns bitcoin 160-bit hash of the public key + /// Returns bitcoin 160-bit hash of the public key. pub fn pubkey_hash(&self) -> PubkeyHash { self.with_serialized(PubkeyHash::hash) } /// Returns bitcoin 160-bit hash of the public key for witness program @@ -77,12 +77,12 @@ impl PublicKey { Ok(key.p2wpkh_script_code()) } - /// Write the public key into a writer + /// Writes the public key into a writer. pub fn write_into(&self, writer: &mut W) -> Result<(), io::Error> { self.with_serialized(|bytes| writer.write_all(bytes)) } - /// Read the public key from a reader + /// Reads the public key from a reader. /// /// This internally reads the first byte before reading the rest, so /// use of a `BufReader` is recommended. @@ -107,14 +107,14 @@ impl PublicKey { }) } - /// Serialize the public key to bytes + /// Serializes the public key to bytes. pub fn to_bytes(self) -> Vec { let mut buf = Vec::new(); self.write_into(&mut buf).expect("vecs don't error"); buf } - /// Serialize the public key into a `SortKey`. + /// Serializes the public key into a `SortKey`. /// /// `SortKey` is not too useful by itself, but it can be used to sort a /// `[PublicKey]` slice using `sort_unstable_by_key`, `sort_by_cached_key`, @@ -174,7 +174,7 @@ impl PublicKey { } } - /// Deserialize a public key from a slice + /// Deserializes a public key from a slice. pub fn from_slice(data: &[u8]) -> Result { let compressed = match data.len() { 33 => true, @@ -191,7 +191,7 @@ impl PublicKey { Ok(PublicKey { compressed, inner: secp256k1::PublicKey::from_slice(data)? }) } - /// Computes the public key as supposed to be used with this secret + /// Computes the public key as supposed to be used with this secret. pub fn from_private_key( secp: &Secp256k1, sk: &PrivateKey, @@ -218,7 +218,7 @@ impl From for XOnlyPublicKey { fn from(pk: PublicKey) -> XOnlyPublicKey { pk.inner.into() } } -/// An opaque return type for PublicKey::to_sort_key +/// An opaque return type for PublicKey::to_sort_key. #[derive(Debug, Hash, PartialEq, Eq, PartialOrd, Ord, Clone, Copy)] pub struct SortKey(ArrayVec); @@ -274,10 +274,10 @@ impl From<&PublicKey> for PubkeyHash { pub struct CompressedPublicKey(pub secp256k1::PublicKey); impl CompressedPublicKey { - /// Returns bitcoin 160-bit hash of the public key + /// Returns bitcoin 160-bit hash of the public key. pub fn pubkey_hash(&self) -> PubkeyHash { PubkeyHash::hash(&self.to_bytes()) } - /// Returns bitcoin 160-bit hash of the public key for witness program + /// Returns bitcoin 160-bit hash of the public key for witness program. pub fn wpubkey_hash(&self) -> WPubkeyHash { WPubkeyHash::from_byte_array(hash160::Hash::hash(&self.to_bytes()).to_byte_array()) } @@ -287,12 +287,12 @@ impl CompressedPublicKey { ScriptBuf::p2wpkh_script_code(self.wpubkey_hash()) } - /// Write the public key into a writer + /// Writes the public key into a writer. pub fn write_into(&self, writer: &mut W) -> Result<(), io::Error> { writer.write_all(&self.to_bytes()) } - /// Read the public key from a reader + /// Reads the public key from a reader. /// /// This internally reads the first byte before reading the rest, so /// use of a `BufReader` is recommended. @@ -319,12 +319,12 @@ impl CompressedPublicKey { /// That's why this type doesn't have the `to_sort_key` method - it would duplicate this one. pub fn to_bytes(&self) -> [u8; 33] { self.0.serialize() } - /// Deserialize a public key from a slice + /// Deserializes a public key from a slice. pub fn from_slice(data: &[u8]) -> Result { secp256k1::PublicKey::from_slice(data).map(CompressedPublicKey) } - /// Computes the public key as supposed to be used with this secret + /// Computes the public key as supposed to be used with this secret. pub fn from_private_key( secp: &Secp256k1, sk: &PrivateKey, @@ -396,11 +396,11 @@ impl From<&CompressedPublicKey> for WPubkeyHash { /// A Bitcoin ECDSA private key. #[derive(Debug, Copy, Clone, PartialEq, Eq)] pub struct PrivateKey { - /// Whether this private key should be serialized as compressed + /// Whether this private key should be serialized as compressed. pub compressed: bool, - /// The network kind on which this key should be used + /// The network kind on which this key should be used. pub network: NetworkKind, - /// The actual ECDSA key + /// The actual ECDSA key. pub inner: secp256k1::SecretKey, } @@ -413,13 +413,13 @@ impl PrivateKey { PrivateKey::new(secret_key, network.into()) } /// Constructs compressed ECDSA private key from the provided generic Secp256k1 private key - /// and the specified network + /// and the specified network. pub fn new(key: secp256k1::SecretKey, network: impl Into) -> PrivateKey { PrivateKey { compressed: true, network: network.into(), inner: key } } /// Constructs uncompressed (legacy) ECDSA private key from the provided generic Secp256k1 - /// private key and the specified network + /// private key and the specified network. pub fn new_uncompressed( key: secp256k1::SecretKey, network: impl Into, @@ -427,7 +427,7 @@ impl PrivateKey { PrivateKey { compressed: false, network: network.into(), inner: key } } - /// Creates a public key from this private key + /// Creates a public key from this private key. pub fn public_key(&self, secp: &Secp256k1) -> PublicKey { PublicKey { compressed: self.compressed, @@ -435,10 +435,10 @@ impl PrivateKey { } } - /// Serialize the private key to bytes + /// Serializes the private key to bytes. pub fn to_bytes(self) -> Vec { self.inner[..].to_vec() } - /// Deserialize a private key from a slice + /// Deserializes a private key from a slice. pub fn from_slice( data: &[u8], network: impl Into, @@ -446,7 +446,7 @@ impl PrivateKey { Ok(PrivateKey::new(secp256k1::SecretKey::from_slice(data)?, network)) } - /// Format the private key to WIF format. + /// Formats the private key to WIF format. #[rustfmt::skip] pub fn fmt_wif(&self, fmt: &mut dyn fmt::Write) -> fmt::Result { let mut ret = [0; 34]; @@ -462,7 +462,7 @@ impl PrivateKey { fmt.write_str(&privkey) } - /// Get WIF encoding of this private key. + /// Gets the WIF encoding of this private key. pub fn to_wif(self) -> String { let mut buf = String::new(); buf.write_fmt(format_args!("{}", self)).unwrap(); @@ -470,7 +470,7 @@ impl PrivateKey { buf } - /// Parse WIF encoded private key. + /// Parses the WIF encoded private key. pub fn from_wif(wif: &str) -> Result { let data = base58::decode_check(wif)?; @@ -686,10 +686,10 @@ impl<'de> serde::Deserialize<'de> for CompressedPublicKey { } } } -/// Untweaked BIP-340 X-coord-only public key +/// Untweaked BIP-340 X-coord-only public key. pub type UntweakedPublicKey = XOnlyPublicKey; -/// Tweaked BIP-340 X-coord-only public key +/// Tweaked BIP-340 X-coord-only public key. #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] #[cfg_attr(feature = "serde", serde(crate = "actual_serde"))] @@ -704,10 +704,10 @@ impl fmt::Display for TweakedPublicKey { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { fmt::Display::fmt(&self.0, f) } } -/// Untweaked BIP-340 key pair +/// Untweaked BIP-340 key pair. pub type UntweakedKeypair = Keypair; -/// Tweaked BIP-340 key pair +/// Tweaked BIP-340 key pair. /// /// # Examples /// @@ -731,9 +731,9 @@ pub struct TweakedKeypair(Keypair); /// A trait for tweaking BIP340 key types (x-only public keys and key pairs). pub trait TapTweak { - /// Tweaked key type with optional auxiliary information + /// Tweaked key type with optional auxiliary information. type TweakedAux; - /// Tweaked key type + /// Tweaked key type. type TweakedKey; /// Tweaks an untweaked key with corresponding public key value and optional script tree merkle @@ -755,7 +755,7 @@ pub trait TapTweak { merkle_root: Option, ) -> Self::TweakedAux; - /// Directly converts an [`UntweakedPublicKey`] to a [`TweakedPublicKey`] + /// Directly converts an [`UntweakedPublicKey`] to a [`TweakedPublicKey`]. /// /// This method is dangerous and can lead to loss of funds if used incorrectly. /// Specifically, in multi-party protocols a peer can provide a value that allows them to steal. @@ -843,7 +843,7 @@ impl TweakedPublicKey { /// Returns the underlying public key. pub fn to_inner(self) -> XOnlyPublicKey { self.0 } - /// Serialize the key as a byte-encoded pair of values. In compressed form + /// Serializes the key as a byte-encoded pair of values. In compressed form /// the y-coordinate is represented by only a single bit, as x determines /// it up to one bit. #[inline] diff --git a/bitcoin/src/crypto/taproot.rs b/bitcoin/src/crypto/taproot.rs index 567cfa537..1cb8a2882 100644 --- a/bitcoin/src/crypto/taproot.rs +++ b/bitcoin/src/crypto/taproot.rs @@ -25,7 +25,7 @@ pub struct Signature { } impl Signature { - /// Deserialize from slice + /// Deserializes the signature from a slice. pub fn from_slice(sl: &[u8]) -> Result { match sl.len() { 64 => { @@ -43,7 +43,7 @@ impl Signature { } } - /// Serialize Signature + /// Serializes the signature. /// /// Note: this allocates on the heap, prefer [`serialize`](Self::serialize) if vec is not needed. pub fn to_bytes(self) -> Vec { @@ -56,7 +56,7 @@ impl Signature { ser_sig } - /// Serialize Signature + /// Serializes the signature. #[deprecated(since = "TBD", note = "Use to_bytes instead")] pub fn to_vec(self) -> Vec { self.to_bytes() } @@ -67,7 +67,7 @@ impl Signature { sig.write_to(writer) } - /// Serializes the signature (without heap allocation) + /// Serializes the signature (without heap allocation). /// /// This returns a type with an API very similar to that of `Box<[u8]>`. /// You can get a slice from it using deref coercions or turn it into an iterator.