Fix function rustdoc titles to use third person
What changed, and why it matters
This commit only changes the wording of code documentation comments (rustdoc) from imperative to third-person style (e.g., 'Parse' to 'Parses'). It also adds a project policy note about this documentation style. No executable code, logic, or behavior was modified, so it has no security impact.
No security action needed. This is a documentation style cleanup. Reviewers may optionally verify that no executable code was accidentally changed, but the diff shows only comment text modifications.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff is a documentation-only patch across 24 Rust source files and docs/policy.md. Every change is in a /// doc comment or in the policy markdown file. There are no changes to function bodies, type definitions, trait implementations, control flow, cryptography, serialization, or network handling. The patch enforces a style guide: function rustdoc summaries must use third person (‘Calculates’, ‘Parses’, ‘Returns’) instead of imperative (‘Calculate’, ‘Parse’, ‘Return’).
Changed components
Documentation comments in bitcoin/src/address/mod.rsDocumentation comments in bitcoin/src/bip32.rsDocumentation comments in bitcoin/src/consensus/encode.rsDocumentation comments in bitcoin/src/merkle_tree/block.rsDocumentation comments in bitcoin/src/pow.rsDocumentation comments in bitcoin/src/psbt/serialize.rsDocumentation comments in bitcoin/src/sign_message.rsDocumentation comments in chacha20_poly1305/src/chacha20.rsDocumentation comments in chacha20_poly1305/src/poly1305.rsDocumentation comments in consensus_encoding/src/encode/mod.rsDocumentation comments in docs/policy.mdDocumentation comments in hashes/src/cmp.rsDocumentation comments in hashes/src/hkdf/mod.rsDocumentation comments in hashes/src/lib.rsDocumentation comments in hashes/src/sha256/mod.rsDocumentation comments in hashes/src/siphash24/mod.rsDocumentation comments in p2p/src/address.rsDocumentation comments in p2p/src/lib.rsDocumentation comments in p2p/src/message.rsDocumentation comments in p2p/src/message_blockdata.rsDocumentation comments in p2p/src/message_network.rsDocumentation comments in primitives/src/witness.rsDocumentation comments in units/src/amount/mod.rsDocumentation comments in units/src/locktime/relative/mod.rsInspect captured patch +82 / −77
diff --git a/bitcoin/src/address/mod.rs b/bitcoin/src/address/mod.rs
index 04e81eae..42d8f766 100644
--- a/bitcoin/src/address/mod.rs
+++ b/bitcoin/src/address/mod.rs
@@ -900,7 +900,7 @@ impl Address<NetworkUnchecked> {
#[inline]
pub fn assume_checked(self) -> Address { Address::from_inner(self.into_inner()) }
- /// Parse a bech32 Address string
+ /// Parses a bech32 Address string
pub fn from_bech32_str(s: &str) -> Result<Address<NetworkUnchecked>, Bech32Error> {
let (hrp, witness_version, data) =
bech32::segwit::decode(s).map_err(|e| Bech32Error::ParseBech32(ParseBech32Error(e)))?;
@@ -913,7 +913,7 @@ impl Address<NetworkUnchecked> {
Ok(Address::from_inner(inner))
}
- /// Parse a base58 Address string
+ /// Parses a base58 Address string
pub fn from_base58_str(s: &str) -> Result<Address<NetworkUnchecked>, Base58Error> {
if s.len() > 50 {
return Err(LegacyAddressTooLongError { length: s.len() }.into());
diff --git a/bitcoin/src/bip32.rs b/bitcoin/src/bip32.rs
index cb4088d7..3e86f503 100644
--- a/bitcoin/src/bip32.rs
+++ b/bitcoin/src/bip32.rs
@@ -410,7 +410,7 @@ pub struct DerivationPathIterator<'a> {
}
impl<'a> DerivationPathIterator<'a> {
- /// Start a new [DerivationPathIterator] at the given child.
+ /// Starts a new [DerivationPathIterator] at the given child.
pub fn start_from(path: &'a DerivationPath, start: ChildNumber) -> DerivationPathIterator<'a> {
DerivationPathIterator { base: path, next_child: Some(start) }
}
@@ -447,25 +447,25 @@ impl DerivationPath {
DerivationPath(path)
}
- /// Convert into a [DerivationPath] that is a child of this one.
+ /// Converts into a [DerivationPath] that is a child of this one.
pub fn into_child(self, cn: ChildNumber) -> DerivationPath {
let mut path = self.0;
path.push(cn);
DerivationPath(path)
}
- /// Get an [Iterator] over the children of this [DerivationPath]
+ /// Gets an [Iterator] over the children of this [DerivationPath]
/// starting with the given [ChildNumber].
pub fn children_from(&self, cn: ChildNumber) -> DerivationPathIterator<'_> {
DerivationPathIterator::start_from(self, cn)
}
- /// Get an [Iterator] over the unhardened children of this [DerivationPath].
+ /// Gets an [Iterator] over the unhardened children of this [DerivationPath].
pub fn normal_children(&self) -> DerivationPathIterator<'_> {
DerivationPathIterator::start_from(self, ChildNumber::Normal { index: 0 })
}
- /// Get an [Iterator] over the hardened children of this [DerivationPath].
+ /// Gets an [Iterator] over the hardened children of this [DerivationPath].
pub fn hardened_children(&self) -> DerivationPathIterator<'_> {
DerivationPathIterator::start_from(self, ChildNumber::Hardened { index: 0 })
}
@@ -930,7 +930,7 @@ impl Xpub {
Ok(pk)
}
- /// Compute the scalar tweak added to this key to get a child key
+ /// Computes the scalar tweak added to this key to get a child key
pub fn ckd_pub_tweak(
&self,
i: ChildNumber,
diff --git a/bitcoin/src/consensus/encode.rs b/bitcoin/src/consensus/encode.rs
index f9ddb6c4..a4919edb 100644
--- a/bitcoin/src/consensus/encode.rs
+++ b/bitcoin/src/consensus/encode.rs
@@ -55,7 +55,7 @@ pub fn deserialize<T: Decodable>(data: &[u8]) -> Result<T, DeserializeError> {
}
}
-/// Deserialize any decodable type from a hex string, will error if said deserialization
+/// Deserializes any decodable type from a hex string, will error if said deserialization
/// doesn't consume the entire vector.
pub fn deserialize_hex<T: Decodable>(hex: &str) -> Result<T, FromHexError> {
let iter = hex::HexSliceToBytesIter::new(hex)?;
@@ -263,7 +263,7 @@ pub trait Encodable {
/// Data which can be encoded in a consensus-consistent way.
pub trait Decodable: Sized {
- /// Decode `Self` from a size-limited reader.
+ /// Decodes `Self` from a size-limited reader.
///
/// Like `consensus_decode` but relies on the reader being limited in the amount of data it
/// returns, e.g. by being wrapped in [`std::io::Take`].
@@ -301,7 +301,7 @@ pub trait Decodable: Sized {
Self::consensus_decode(reader)
}
- /// Decode an object with a well-defined format.
+ /// Decodes an object with a well-defined format.
///
/// This is the method that should be implemented for a typical, fixed sized type
/// implementing this trait. Default implementation is wrapping the reader
diff --git a/bitcoin/src/merkle_tree/block.rs b/bitcoin/src/merkle_tree/block.rs
index 01dec4cd..43f530f9 100644
--- a/bitcoin/src/merkle_tree/block.rs
+++ b/bitcoin/src/merkle_tree/block.rs
@@ -102,7 +102,7 @@ impl MerkleBlock {
MerkleBlock { header: *header, txn: pmt }
}
- /// Extract the matching txid's represented by this partial Merkle tree
+ /// Extracts the matching txid's represented by this partial Merkle tree
/// and their respective indices within the partial tree.
/// returns Ok(()) on success, or error in case of failure
pub fn extract_matches(
@@ -235,7 +235,7 @@ impl PartialMerkleTree {
pmt
}
- /// Extract the matching txid's represented by this partial Merkle tree
+ /// Extracts the matching txid's represented by this partial Merkle tree
/// and their respective indices within the partial tree.
/// returns the Merkle root, or error in case of failure
pub fn extract_matches(
@@ -297,7 +297,7 @@ impl PartialMerkleTree {
(self.num_transactions + (1 << height) - 1) >> height
}
- /// Calculate the hash of a node in the Merkle tree (at leaf level: the txid's themselves)
+ /// Calculates the hash of a node in the Merkle tree (at leaf level: the txid's themselves)
fn calc_hash(&self, height: u32, pos: u32, txids: &[Txid]) -> TxMerkleNode {
if height == 0 {
// Hash at height 0 is the txid itself
diff --git a/bitcoin/src/pow.rs b/bitcoin/src/pow.rs
index 246b3f96..1a102f69 100644
--- a/bitcoin/src/pow.rs
+++ b/bitcoin/src/pow.rs
@@ -824,7 +824,7 @@ impl U256 {
f.pad_integral(true, "", s)
}
- /// Convert self to f64.
+ /// Converts self to f64.
#[inline]
fn to_f64(self) -> f64 {
// Reference: https://blog.m-ou.se/floats/
diff --git a/bitcoin/src/psbt/serialize.rs b/bitcoin/src/psbt/serialize.rs
index 457dc73d..c529df97 100644
--- a/bitcoin/src/psbt/serialize.rs
+++ b/bitcoin/src/psbt/serialize.rs
@@ -28,28 +28,28 @@ use crate::witness::Witness;
/// A trait for serializing a value as raw data for insertion into PSBT
/// key-value maps.
pub(crate) trait Serialize {
- /// Serialize a value as raw data.
+ /// Serializes a value as raw data.
fn serialize(&self) -> Vec<u8>;
}
/// A trait for deserializing a value from raw data in PSBT key-value maps.
pub(crate) trait Deserialize: Sized {
- /// Deserialize a value from raw data.
+ /// Deserializes a value from raw data.
fn deserialize(bytes: &[u8]) -> Result<Self, Error>;
}
impl Psbt {
- /// Serialize a value as bytes in hex.
+ /// Serializes a value as bytes in hex.
pub fn serialize_hex(&self) -> String { self.serialize().to_lower_hex_string() }
- /// Serialize as raw binary data
+ /// Serializes as raw binary data
pub fn serialize(&self) -> Vec<u8> {
let mut buf: Vec<u8> = Vec::new();
self.serialize_to_writer(&mut buf).expect("Writing to Vec can't fail");
buf
}
- /// Serialize the PSBT into a writer.
+ /// Serializes the PSBT into a writer.
pub fn serialize_to_writer(&self, w: &mut impl Write) -> io::Result<usize> {
let mut written_len = 0;
@@ -75,12 +75,12 @@ impl Psbt {
Ok(written_len)
}
- /// Deserialize a value from raw binary data.
+ /// Deserializes a value from raw binary data.
pub fn deserialize(mut bytes: &[u8]) -> Result<Self, Error> {
Self::deserialize_from_reader(&mut bytes)
}
- /// Deserialize a value from raw binary data read from a `BufRead` object.
+ /// Deserializes a value from raw binary data read from a `BufRead` object.
pub fn deserialize_from_reader<R: io::BufRead>(r: &mut R) -> Result<Self, Error> {
const MAGIC_BYTES: &[u8] = b"psbt";
diff --git a/bitcoin/src/sign_message.rs b/bitcoin/src/sign_message.rs
index d5f2be84..14cb7e32 100644
--- a/bitcoin/src/sign_message.rs
+++ b/bitcoin/src/sign_message.rs
@@ -100,7 +100,7 @@ mod message_signing {
MessageSignature { signature, compressed }
}
- /// Serialize to bytes.
+ /// Serializes to bytes.
pub fn serialize(&self) -> [u8; 65] {
let (recid, raw) = self.signature.serialize_compact();
let mut serialized = [0u8; 65];
@@ -143,7 +143,7 @@ mod message_signing {
Ok(PublicKey { inner: pubkey, compressed: self.compressed })
}
- /// Verify that the signature signs the message and was signed by the given address.
+ /// Verifies that the signature signs the message and was signed by the given address.
///
/// To get the message hash from a message, use [super::signed_msg_hash].
pub fn is_signed_by_address<C: secp256k1::Verification>(
@@ -172,7 +172,7 @@ mod message_signing {
use crate::prelude::String;
impl MessageSignature {
- /// Convert a signature from base64 encoding.
+ /// Converts a signature from base64 encoding.
pub fn from_base64(s: &str) -> Result<MessageSignature, MessageSignatureError> {
if s.len() != 88 {
return Err(MessageSignatureError::InvalidLength);
@@ -184,7 +184,7 @@ mod message_signing {
MessageSignature::from_byte_array(&byte_array).map_err(MessageSignatureError::from)
}
- /// Convert to base64 encoding.
+ /// Converts to base64 encoding.
pub fn to_base64(self) -> String { BASE64_STANDARD.encode(self.serialize()) }
}
diff --git a/chacha20_poly1305/src/chacha20.rs b/chacha20_poly1305/src/chacha20.rs
index b9388923..16664f70 100644
--- a/chacha20_poly1305/src/chacha20.rs
+++ b/chacha20_poly1305/src/chacha20.rs
@@ -193,7 +193,7 @@ impl State {
[a, b, c, d]
}
- /// Perform a round on "columns" and then "diagonals" of the state.
+ /// Performs a round on "columns" and then "diagonals" of the state.
///
/// The column quarter rounds are made up of indexes: `[0,4,8,12]`, `[1,5,9,13]`, `[2,6,10,14]`, `[3,7,11,15]`.
/// The diagonals quarter rounds are made up of indexes: `[0,5,10,15]`, `[1,6,11,12]`, `[2,7,8,13]`, `[3,4,9,14]`.
@@ -222,7 +222,7 @@ impl State {
[a, b, c, d]
}
- /// Transform the state by performing the ChaCha block function.
+ /// Transforms the state by performing the ChaCha block function.
#[inline(always)]
fn chacha_block(&mut self) {
let mut working_state = self.matrix;
@@ -276,7 +276,7 @@ impl ChaCha20 {
ChaCha20 { key, nonce, block_count: block, seek_offset_bytes: 0 }
}
- /// Get the keystream for a specific block.
+ /// Gets the keystream for a specific block.
#[inline(always)]
fn keystream_at_block(&self, block: u32) -> [u8; 64] {
let mut state = State::new(self.key, self.nonce, block);
@@ -331,16 +331,16 @@ impl ChaCha20 {
}
}
- /// Get the keystream for specified block.
+ /// Gets the keystream for specified block.
pub fn get_keystream(&self, block: u32) -> [u8; 64] { self.keystream_at_block(block) }
- /// Update the index of the keystream to the given byte.
+ /// Updates the index of the keystream to the given byte.
pub fn seek(&mut self, seek: u32) {
self.block_count = seek / 64;
self.seek_offset_bytes = (seek % 64) as usize;
}
- /// Update the index of the keystream to a block.
+ /// Updates the index of the keystream to a block.
pub fn block(&mut self, block: u32) {
self.block_count = block;
self.seek_offset_bytes = 0;
diff --git a/chacha20_poly1305/src/poly1305.rs b/chacha20_poly1305/src/poly1305.rs
index 9e47602e..c34ba3f8 100644
--- a/chacha20_poly1305/src/poly1305.rs
+++ b/chacha20_poly1305/src/poly1305.rs
@@ -27,7 +27,7 @@ pub struct Poly1305 {
}
impl Poly1305 {
- /// Initialize authenticator with a 32-byte one-time secret key.
+ /// Initializes authenticator with a 32-byte one-time secret key.
pub const fn new(key: [u8; 32]) -> Self {
// Taken from Donna. Assigns r to a 26-bit 5-limb number while simultaneously 'clamping' r.
let r0 = u32::from_le_bytes([key[0], key[1], key[2], key[3]]) & 0x3ffffff;
@@ -50,7 +50,7 @@ impl Poly1305 {
}
}
- /// Add message to be authenticated, can be called multiple times before creating tag.
+ /// Adds message to be authenticated, can be called multiple times before creating tag.
pub fn input(&mut self, message: &[u8]) {
// Process previous leftovers if the message is long enough to fill the leftovers buffer. If
// the message is too short then it will just be added to the leftovers at the end. Now if there
@@ -95,7 +95,7 @@ impl Poly1305 {
}
}
- /// Generate authentication tag.
+ /// Generates authentication tag.
pub fn tag(mut self) -> [u8; 16] {
// Add any remaining leftovers to accumulator.
if self.leftovers_len > 0 {
diff --git a/consensus_encoding/src/encode/mod.rs b/consensus_encoding/src/encode/mod.rs
index 3530928f..8844b9ef 100644
--- a/consensus_encoding/src/encode/mod.rs
+++ b/consensus_encoding/src/encode/mod.rs
@@ -62,7 +62,7 @@ macro_rules! encoder_newtype{
}
}
-/// Encode an object into a hash engine.
+/// Encodes an object into a hash engine.
///
/// Consumes and returns the hash engine to make it easier to call
/// [`hashes::HashEngine::finalize`] directly on the result.
diff --git a/docs/policy.md b/docs/policy.md
index 7e3a8a03..183960c5 100644
--- a/docs/policy.md
+++ b/docs/policy.md
@@ -69,14 +69,14 @@ Note, can use this exact doc format.
### Special treatment of `bitcoin`, `primitives`, `units`
-`bitcoin`, `primitives`, and `units` should each be a superset of the crates below.
+`bitcoin`, `primitives`, and `units` should each be a superset of the crates below.
E.g for any `units::Foo`, there will be a `primitives::Foo`, and `bitcoin::Foo`. This goes for all
types and modules.
For these three crates:
-- Non-error re-exports use `doc(inline)`.
+- Non-error re-exports use `doc(inline)`.
- Error re-exports use `doc(no_inline)`.
- Error types that are directly in the API are re-exported.
- Other error types are available in an `error` module.
@@ -93,15 +93,15 @@ pub mod foo {
pub struct FooBar { ... };
/// Some function.
- pub some_function() -> SomeError {
+ pub some_function() -> SomeError {
// Example error logic
SomeError::Foo(FooError { ... })
}
-
+
pub mod error {
/// Example error used 'directly' in the public API.
pub enum SomeError { ... };
-
+
/// Abstracts the details of a foo-related error.
pub struct FooError { ... };
}
@@ -293,6 +293,11 @@ impl FooBar {
}
```
+Note usage of third person instead of imperative.
+
+Good: `/// Calculates the distance to the moon.`
+Bad: `/// Calculate the distance to the moon.`
+
Add Panics section if any input to the function can trigger a panic.
Generally we prefer to have non-panicking APIs but it is impractical in some cases. If you're not
diff --git a/hashes/src/cmp.rs b/hashes/src/cmp.rs
index 99ccea99..2f971d39 100644
--- a/hashes/src/cmp.rs
+++ b/hashes/src/cmp.rs
@@ -2,7 +2,7 @@
//! Useful comparison functions.
-/// Compare two slices for equality in fixed time. Panics if the slices are of non-equal length.
+/// Compares two slices for equality in fixed time. Panics if the slices are of non-equal length.
///
/// This works by XOR'ing each byte of the two inputs together and keeping an OR counter of the
/// results.
diff --git a/hashes/src/hkdf/mod.rs b/hashes/src/hkdf/mod.rs
index ce789989..8d852d1a 100644
--- a/hashes/src/hkdf/mod.rs
+++ b/hashes/src/hkdf/mod.rs
@@ -42,7 +42,7 @@ impl<T: HashEngine> Hkdf<T>
where
T: Default,
{
- /// Initialize a HKDF by performing the extract step.
+ /// Initializes a HKDF by performing the extract step.
pub fn new(salt: &[u8], ikm: &[u8]) -> Self {
let mut engine: HmacEngine<T> = HmacEngine::new(salt);
engine.input(ikm);
diff --git a/hashes/src/lib.rs b/hashes/src/lib.rs
index de518bf9..bcd32f52 100644
--- a/hashes/src/lib.rs
+++ b/hashes/src/lib.rs
@@ -191,10 +191,10 @@ pub trait HashEngine: Clone {
/// Length of the hash's internal block size, in bytes.
const BLOCK_SIZE: usize;
- /// Add data to the hash engine.
+ /// Adds data to the hash engine.
fn input(&mut self, data: &[u8]);
- /// Return the number of bytes already input into the engine.
+ /// Returns the number of bytes already input into the engine.
fn n_bytes_hashed(&self) -> u64;
/// Finalizes this engine.
diff --git a/hashes/src/sha256/mod.rs b/hashes/src/sha256/mod.rs
index 63f1362d..bc3068aa 100644
--- a/hashes/src/sha256/mod.rs
+++ b/hashes/src/sha256/mod.rs
@@ -179,7 +179,7 @@ pub struct Midstate {
}
impl Midstate {
- /// Construct a new [`Midstate`] from the `state` and the `bytes_hashed` to get to that state.
+ /// Constructs a new [`Midstate`] from the `state` and the `bytes_hashed` to get to that state.
///
/// # Panics
///
diff --git a/hashes/src/siphash24/mod.rs b/hashes/src/siphash24/mod.rs
index 664ee670..316cdc6c 100644
--- a/hashes/src/siphash24/mod.rs
+++ b/hashes/src/siphash24/mod.rs
@@ -34,7 +34,7 @@ macro_rules! compress {
}};
}
-/// Load an integer of the desired type from a byte stream, in LE order. Uses
+/// Loads an integer of the desired type from a byte stream, in LE order. Uses
/// `copy_nonoverlapping` to let the compiler generate the most efficient way
/// to load it from a possibly unaligned address.
///
@@ -214,7 +214,7 @@ impl Hash {
pub fn from_u64(hash: u64) -> Hash { Hash(hash.to_le_bytes()) }
}
-/// Load a u64 using up to 7 bytes of a byte slice.
+/// Loads a u64 using up to 7 bytes of a byte slice.
///
/// Unsafe because: unchecked indexing at `start..start+len`.
#[inline]
diff --git a/p2p/src/address.rs b/p2p/src/address.rs
index 9b909514..3efa8328 100644
--- a/p2p/src/address.rs
+++ b/p2p/src/address.rs
@@ -31,7 +31,7 @@ pub struct Address {
const ONION: [u16; 3] = [0xFD87, 0xD87E, 0xEB43];
impl Address {
- /// Construct a new address message for a socket
+ /// Constructs a new address message for a socket
pub fn new(socket: &SocketAddr, services: ServiceFlags) -> Address {
let (address, port) = match *socket {
SocketAddr::V4(addr) => (addr.ip().to_ipv6_mapped().segments(), addr.port()),
@@ -40,13 +40,13 @@ impl Address {
Address { address, port, services }
}
- /// Build an useless address that cannot be connected to. One may find this desirable if it is
+ /// Builds a useless address that cannot be connected to. One may find this desirable if it is
/// known the data will be ignored by the recipient.
pub const fn useless() -> Address {
Address { services: ServiceFlags::NONE, address: [0; 8], port: 0 }
}
- /// Extract socket address from an [Address] message.
+ /// Extracts socket address from an [Address] message.
/// This will return [io::Error] [io::ErrorKind::AddrNotAvailable]
/// if the message contains a Tor address.
pub fn socket_addr(&self) -> Result<SocketAddr, io::Error> {
@@ -92,7 +92,7 @@ impl Decodable for Address {
}
}
-/// Read a big-endian address from reader.
+/// Reads a big-endian address from reader.
fn read_be_address<R: Read + ?Sized>(r: &mut R) -> Result<[u16; 8], encode::Error> {
let mut address = [0u16; 8];
let mut buf = [0u8; 2];
@@ -316,7 +316,7 @@ pub struct AddrV2Message {
}
impl AddrV2Message {
- /// Extract socket address from an [AddrV2Message] message.
+ /// Extracts socket address from an [AddrV2Message] message.
/// This will return [io::Error] [io::ErrorKind::AddrNotAvailable]
/// if the address type can't be converted into a [SocketAddr].
pub fn socket_addr(&self) -> Result<SocketAddr, io::Error> {
diff --git a/p2p/src/lib.rs b/p2p/src/lib.rs
index d941e456..299a1b1f 100644
--- a/p2p/src/lib.rs
+++ b/p2p/src/lib.rs
@@ -95,7 +95,7 @@ impl ProtocolVersion {
}
impl ProtocolVersion {
- /// Construct a protocol version that is not well-known.
+ /// Constructs a protocol version that is not well-known.
pub fn from_nonstandard(version: u32) -> Self { Self(version) }
}
@@ -168,7 +168,7 @@ impl ServiceFlags {
*self
}
- /// Remove [ServiceFlags] from this.
+ /// Removes [ServiceFlags] from this.
///
/// Returns itself.
#[must_use]
@@ -177,7 +177,7 @@ impl ServiceFlags {
*self
}
- /// Check whether [ServiceFlags] are included in this one.
+ /// Checks whether [ServiceFlags] are included in this one.
pub fn has(self, flags: ServiceFlags) -> bool { (self.0 | flags.0) == self.0 }
/// Gets the integer representation of this [`ServiceFlags`].
@@ -289,10 +289,10 @@ impl Magic {
/// Bitcoin regtest network magic bytes.
pub const REGTEST: Self = Self([0xFA, 0xBF, 0xB5, 0xDA]);
- /// Construct a new network magic from bytes.
+ /// Constructs a new network magic from bytes.
pub const fn from_bytes(bytes: [u8; 4]) -> Magic { Magic(bytes) }
- /// Get network magic bytes.
+ /// Gets network magic bytes.
pub fn to_bytes(self) -> [u8; 4] { self.0 }
/// Returns the magic bytes for the network defined by `params`.
diff --git a/p2p/src/message.rs b/p2p/src/message.rs
index 7eb5d740..effebc31 100644
--- a/p2p/src/message.rs
+++ b/p2p/src/message.rs
@@ -291,7 +291,7 @@ pub enum NetworkMessage {
}
impl NetworkMessage {
- /// Return the message command as a static string reference.
+ /// Returns the message command as a static string reference.
///
/// This returns `"unknown"` for [NetworkMessage::Unknown],
/// regardless of the actual command in the unknown message.
@@ -338,7 +338,7 @@ impl NetworkMessage {
}
}
- /// Return the CommandString for the message command.
+ /// Returns the CommandString for the message command.
pub fn command(&self) -> CommandString {
match *self {
NetworkMessage::Unknown { command: ref c, .. } => c.clone(),
@@ -368,14 +368,14 @@ impl RawNetworkMessage {
/// Magic bytes to identify the network these messages are meant for
pub fn magic(&self) -> &Magic { &self.magic }
- /// Return the message command as a static string reference.
+ /// Returns the message command as a static string reference.
///
/// This returns `"unknown"` for [NetworkMessage::Unknown],
/// regardless of the actual command in the unknown message.
/// Use the [Self::command] method to get the command for unknown messages.
pub fn cmd(&self) -> &'static str { self.payload.cmd() }
- /// Return the CommandString for the message command.
+ /// Returns the CommandString for the message command.
pub fn command(&self) -> CommandString { self.payload.command() }
}
@@ -389,14 +389,14 @@ impl V2NetworkMessage {
/// The actual message data
pub fn payload(&self) -> &NetworkMessage { &self.payload }
- /// Return the message command as a static string reference.
+ /// Returns the message command as a static string reference.
///
/// This returns `"unknown"` for [NetworkMessage::Unknown],
/// regardless of the actual command in the unknown message.
/// Use the [Self::command] method to get the command for unknown messages.
pub fn cmd(&self) -> &'static str { self.payload.cmd() }
- /// Return the CommandString for the message command.
+ /// Returns the CommandString for the message command.
pub fn command(&self) -> CommandString { self.payload.command() }
}
diff --git a/p2p/src/message_blockdata.rs b/p2p/src/message_blockdata.rs
index 00760a27..4265c1f1 100644
--- a/p2p/src/message_blockdata.rs
+++ b/p2p/src/message_blockdata.rs
@@ -45,7 +45,7 @@ pub enum Inventory {
}
impl Inventory {
- /// Return the item value represented as a SHA256-d hash.
+ /// Returns the item value represented as a SHA256-d hash.
///
/// Returns [None] only for [Inventory::Error] who's hash value is meaningless.
pub fn network_hash(&self) -> Option<[u8; 32]> {
diff --git a/p2p/src/message_network.rs b/p2p/src/message_network.rs
index 2eb30242..27626de5 100644
--- a/p2p/src/message_network.rs
+++ b/p2p/src/message_network.rs
@@ -119,7 +119,7 @@ impl UserAgent {
panic!("user agent cannot exceed 256 characters.");
}
}
- /// Build a new user agent from the lowest level client software. For example: `Satoshi` is
+ /// Builds a new user agent from the lowest level client software. For example: `Satoshi` is
/// used by Bitcoin Core.
///
/// # Panics
@@ -133,12 +133,12 @@ impl UserAgent {
Self { user_agent: agent }
}
- /// Build a user agent, ignoring BIP-0014 recommendations.
+ /// Builds a user agent, ignoring BIP-0014 recommendations.
pub fn from_nonstandard<S: ToString>(agent: S) -> Self {
Self { user_agent: agent.to_string() }
}
- /// Add a client to the user agent string. Examples may include the name of a wallet software.
+ /// Adds a client to the user agent string. Examples may include the name of a wallet software.
///
/// # Panics
///
@@ -174,12 +174,12 @@ pub struct UserAgentVersion {
}
impl UserAgentVersion {
- /// Create a user agent client version associated with a name.
+ /// Creates a user agent client version associated with a name.
pub const fn new(software_version: ClientSoftwareVersion) -> Self {
Self { version: software_version, comments: None }
}
- /// Add a comment to the version. Typical comments describe the operating system or platform
+ /// Adds a comment to the version. Typical comments describe the operating system or platform
/// that is executing the program, however these may be any comment.
///
/// An example may include `Android`.
@@ -320,7 +320,7 @@ impl Alert {
100, 101, 32, 114, 101, 113, 117, 105, 114, 101, 100, 0,
];
- /// Build the final alert to send to a potentially vulnerable peer.
+ /// Builds the final alert to send to a potentially vulnerable peer.
pub fn final_alert() -> Self { Self(Self::FINAL_ALERT.into()) }
/// The final alert advertised by Bitcoin Core. This alert is sent if the advertised protocol
diff --git a/primitives/src/witness.rs b/primitives/src/witness.rs
index 02ad6ffa..693e1b8b 100644
--- a/primitives/src/witness.rs
+++ b/primitives/src/witness.rs
@@ -137,7 +137,7 @@ impl Witness {
size
}
- /// Clear the witness.
+ /// Clears the witness.
#[inline]
pub fn clear(&mut self) {
self.content.clear();
@@ -145,13 +145,13 @@ impl Witness {
self.indices_start = 0;
}
- /// Push a new element on the witness, requires an allocation.
+ /// Pushes a new element on the witness, requires an allocation.
#[inline]
pub fn push<T: AsRef<[u8]>>(&mut self, new_element: T) {
self.push_slice(new_element.as_ref());
}
- /// Push a new element slice onto the witness stack.
+ /// Pushes a new element slice onto the witness stack.
fn push_slice(&mut self, new_element: &[u8]) {
self.witness_elements += 1;
let previous_content_end = self.indices_start;
diff --git a/units/src/amount/mod.rs b/units/src/amount/mod.rs
index c62d8054..d799b5ec 100644
--- a/units/src/amount/mod.rs
+++ b/units/src/amount/mod.rs
@@ -406,7 +406,7 @@ fn repeat_char(f: &mut dyn fmt::Write, c: char, count: usize) -> fmt::Result {
Ok(())
}
-/// Format the given satoshi amount in the given denomination.
+/// Formats the given satoshi amount in the given denomination.
fn fmt_satoshi_in(
mut satoshi: u64,
negative: bool,
diff --git a/units/src/locktime/relative/mod.rs b/units/src/locktime/relative/mod.rs
index a61774b0..de1719fc 100644
--- a/units/src/locktime/relative/mod.rs
+++ b/units/src/locktime/relative/mod.rs
@@ -150,7 +150,7 @@ impl LockTime {
LockTime::Time(NumberOf512Seconds::from_512_second_intervals(intervals))
}
- /// Construct a new [`LockTime`] from seconds, converting the seconds into 512 second interval
+ /// Constructs a new [`LockTime`] from seconds, converting the seconds into 512 second interval
/// with truncating division.
///
/// # Errors
@@ -164,7 +164,7 @@ impl LockTime {
}
}
- /// Construct a new [`LockTime`] from seconds, converting the seconds into 512 second interval
+ /// Constructs a new [`LockTime`] from seconds, converting the seconds into 512 second interval
/// with ceiling division.
///
/// # Errors
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.