Merge rust-bitcoin/rust-bitcoin#7041: Improve Returns docs
What changed, and why it matters
This commit is purely a documentation cleanup. It puts code words like true, false, None, and Err inside backticks in Rust doc comments, fixes a grammar mistake (who's -> whose), and rewords descriptions of U256 arithmetic overflow so they correctly say an overflow did occur rather than would occur. No program logic, function behavior, or security properties were changed.
No security action needed. Treat as a normal documentation improvement.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The merge commit contains only documentation edits across 17 files. Changes are limited to Rust doc-comment text: backtick-quoting return-value literals, correcting the grammar of network_hash docs, and clarifying U256 overflowing_add/sub/mul return documentation. No executable code, type signatures, algorithms, or public APIs were modified. There is no security-relevant change.
Changed components
Inspect captured patch +61 / −59
### addresses/src/lib.rs
@@ -845,7 +845,7 @@ impl Address {
/// Gets the address type of the [`Address`].
///
- /// Returns None if unknown, non-standard or related to the future witness version.
+ /// Returns `None` if unknown, non-standard or related to the future witness version.
#[inline]
pub fn address_type(&self) -> Option<AddressType> {
match *self.inner() {
@@ -993,7 +993,7 @@ impl Address {
#[cfg(feature = "alloc")]
pub fn to_qr_uri(self) -> String { format!("bitcoin:{:#}", self) }
- /// Returns true if the given pubkey is directly related to the address payload.
+ /// Returns `true` if the given pubkey is directly related to the address payload.
///
/// This is determined by directly comparing the address payload with either the
/// hash of the given public key or the SegWit redeem hash generated from the
@@ -1008,15 +1008,15 @@ impl Address {
|| (*segwit_redeem_hash(pubkey_hash).as_byte_array() == *payload)
}
- /// Returns true if the supplied xonly public key can be used to derive the address.
+ /// Returns `true` if the supplied xonly public key can be used to derive the address.
///
/// This will only work for Taproot addresses. The Public Key is
/// assumed to have already been tweaked.
pub fn is_related_to_xonly_pubkey(&self, xonly_pubkey: XOnlyPublicKey) -> bool {
xonly_pubkey.serialize().0 == *self.payload_as_bytes()
}
- /// Returns true if the address creates a particular script
+ /// Returns `true` if the address creates a particular script
/// This function doesn't make any allocations.
#[cfg(feature = "alloc")]
pub fn matches_script_pubkey(&self, script: &ScriptPubKey) -> bool {
### addresses/src/witness_program.rs
@@ -137,20 +137,20 @@ impl WitnessProgram {
.expect("witness programs are always smaller than max size of PushBytes")
}
- /// Returns true if this witness program is for a P2WPKH output.
+ /// Returns `true` if this witness program is for a P2WPKH output.
pub fn is_p2wpkh(&self) -> bool {
self.version == WitnessVersion::V0 && self.program.len() == 20
}
- /// Returns true if this witness program is for a P2WSH output.
+ /// Returns `true` if this witness program is for a P2WSH output.
pub fn is_p2wsh(&self) -> bool {
self.version == WitnessVersion::V0 && self.program.len() == 32
}
- /// Returns true if this witness program is for a P2TR output.
+ /// Returns `true` if this witness program is for a P2TR output.
pub fn is_p2tr(&self) -> bool { self.version == WitnessVersion::V1 && self.program.len() == 32 }
- /// Returns true if this witness program is for a P2A output.
+ /// Returns `true` if this witness program is for a P2A output.
pub fn is_p2a(&self) -> bool {
self.version == WitnessVersion::V1 && self.program == P2A_PROGRAM
}
### bitcoin/src/bip158.rs
@@ -91,7 +91,7 @@ impl BlockFilter {
/// Computes the canonical hash for the given filter.
pub fn filter_hash(&self) -> sha256d::Hash { sha256d::Hash::hash(&self.content) }
- /// Returns true if any query matches against this [`BlockFilter`].
+ /// Returns `true` if any query matches against this [`BlockFilter`].
pub fn match_any<I>(&self, block_hash: BlockHash, query: I) -> Result<bool, Error>
where
I: Iterator,
@@ -101,7 +101,7 @@ impl BlockFilter {
filter_reader.match_any(&mut self.content.as_slice(), query)
}
- /// Returns true if all queries match against this [`BlockFilter`].
+ /// Returns `true` if all queries match against this [`BlockFilter`].
pub fn match_all<I>(&self, block_hash: BlockHash, query: I) -> Result<bool, Error>
where
I: Iterator,
@@ -180,7 +180,7 @@ impl BlockFilterReader {
Self { reader: GcsFilterReader::new(k0, k1, M, P) }
}
- /// Returns true if any query matches against this [`BlockFilterReader`].
+ /// Returns `true` if any query matches against this [`BlockFilterReader`].
pub fn match_any<I, R>(&self, reader: &mut R, query: I) -> Result<bool, Error>
where
I: Iterator,
@@ -190,7 +190,7 @@ impl BlockFilterReader {
self.reader.match_any(reader, query)
}
- /// Returns true if all queries match against this [`BlockFilterReader`].
+ /// Returns `true` if all queries match against this [`BlockFilterReader`].
pub fn match_all<I, R>(&self, reader: &mut R, query: I) -> Result<bool, Error>
where
I: Iterator,
@@ -213,7 +213,7 @@ impl GcsFilterReader {
Self { filter: GcsFilter::new(k0, k1, p), m }
}
- /// Returns true if any query matches against this [`GcsFilterReader`].
+ /// Returns `true` if any query matches against this [`GcsFilterReader`].
pub fn match_any<I, R>(&self, reader: &mut R, query: I) -> Result<bool, Error>
where
I: Iterator,
@@ -257,7 +257,7 @@ impl GcsFilterReader {
Ok(false)
}
- /// Returns true if all queries match against this [`GcsFilterReader`].
+ /// Returns `true` if all queries match against this [`GcsFilterReader`].
pub fn match_all<I, R>(&self, reader: &mut R, query: I) -> Result<bool, Error>
where
I: Iterator,
### bitcoin/src/blockdata/transaction.rs
@@ -88,7 +88,7 @@ const TX_IN_BASE_WEIGHT: Weight =
internal_macros::define_extension_trait! {
/// Extension functionality for the [`TxIn`] type.
pub trait TxInExt impl for TxIn {
- /// Returns true if this input enables the [`absolute::LockTime`] (aka `nLockTime`) of its
+ /// Returns `true` if this input enables the [`absolute::LockTime`] (aka `nLockTime`) of its
/// [`Transaction`].
///
/// `nLockTime` is enabled if *any* input enables it. See [`Transaction::is_lock_time_enabled`]
@@ -303,7 +303,7 @@ pub trait TransactionExt: sealed::Sealed {
/// the RBF signal: <https://bitcoinops.org/en/newsletters/2022/10/19/#transaction-replacement-option>.
fn is_explicitly_rbf(&self) -> bool;
- /// Returns true if this [`Transaction`]'s absolute timelock is satisfied at `height`/`time`.
+ /// Returns `true` if this [`Transaction`]'s absolute timelock is satisfied at `height`/`time`.
///
/// # Returns
///
### bitcoin/src/pow.rs
@@ -50,7 +50,7 @@ impl WorkExt for Work {
internal_macros::define_extension_trait! {
/// Extension functionality for the [`Target`] type.
pub trait TargetExt impl for Target {
- /// Returns true if block hash is less than or equal to this [`Target`].
+ /// Returns `true` if block hash is less than or equal to this [`Target`].
///
/// Proof-of-work validity for a block requires the hash of the block to be less than or equal
/// to the target.
@@ -271,7 +271,7 @@ where
}
}
-/// Returns true if `height` ends the difficulty period.
+/// Returns `true` if `height` ends the difficulty period.
fn is_retarget_height(height: BlockHeight, adjustment_interval: u32) -> bool {
height.to_u32() % adjustment_interval == 0
}
### bitcoin/src/taproot/mod.rs
@@ -497,7 +497,7 @@ impl TaprootBuilder {
/// Constructs a new [`TaprootSpendInfo`] with the given internal key.
///
- /// Returns the unmodified builder as Err if the builder is not finalizable.
+ /// Returns the unmodified builder as `Err` if the builder is not finalizable.
/// See also [`TaprootBuilder::is_finalizable`]
pub fn finalize<K: Into<XOnlyPublicKey>>(
mut self,
### include/array_newtype.rs
@@ -188,7 +188,7 @@ macro_rules! impl_array_newtype {
#[inline]
pub fn len(&self) -> usize { $len }
- /// Returns whether the object, as an array, is empty. Always false.
+ /// Returns whether the object, as an array, is empty. Always `false`.
#[inline]
pub fn is_empty(&self) -> bool { false }
}
### internals/src/array_vec.rs
@@ -274,7 +274,7 @@ impl<T: Copy, const CAP: usize> ArrayVec<T, CAP> {
/// Removes the last element, returning it.
///
- /// Returns None if the `ArrayVec` is empty.
+ /// Returns `None` if the `ArrayVec` is empty.
#[cfg_attr(creusot, ensures(self@.len() == 0 ==> result == None))]
#[cfg_attr(creusot, ensures(self@.len() == 0 ==> (^self) == (*self)))]
#[cfg_attr(creusot, ensures(self@.len() > 0 ==> result == Some(self@[self@.len() - 1])))]
### internals/src/u256.rs
@@ -63,7 +63,7 @@ impl U256 {
fn is_zero(&self) -> bool { self.0 == 0 && self.1 == 0 }
- /// Returns true if `self` is equal to [`U256::MAX`].
+ /// Returns `true` if `self` is equal to [`U256::MAX`].
pub fn is_max(&self) -> bool { self.0 == u128::MAX && self.1 == u128::MAX }
/// Returns the low 32 bits.
@@ -165,8 +165,8 @@ impl U256 {
///
/// # Returns
///
- /// A tuple of the addition along with a boolean indicating whether an arithmetic
- /// overflow would occur. If an overflow would have occurred then the wrapped value is returned.
+ /// The sum of `self` and `rhs`, along with a boolean indicating whether an arithmetic
+ /// overflow occurred. If an overflow occurred, the wrapped sum is returned.
#[must_use = "this returns the result of the operation, without modifying the original"]
pub fn overflowing_add(self, rhs: Self) -> (Self, bool) {
let mut ret = Self::ZERO;
@@ -191,8 +191,8 @@ impl U256 {
///
/// # Returns
///
- /// A tuple of the subtraction along with a boolean indicating whether an arithmetic
- /// overflow would occur. If an overflow would have occurred then the wrapped value is returned.
+ /// The difference of `self` and `rhs`, along with a boolean indicating whether an arithmetic
+ /// overflow occurred. If an overflow occurred, the wrapped difference is returned.
#[must_use = "this returns the result of the operation, without modifying the original"]
pub fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
let ret = self.wrapping_add(!rhs).wrapping_add(Self::ONE);
@@ -204,9 +204,8 @@ impl U256 {
///
/// # Returns
///
- /// A tuple of the multiplication along with a boolean
- /// indicating whether an arithmetic overflow would occur. If an
- /// overflow would have occurred then the wrapped value is returned.
+ /// The product of `self` and `rhs`, along with a boolean indicating whether an arithmetic
+ /// overflow occurred. If an overflow occurred, the wrapped product is returned.
#[must_use = "this returns the result of the operation, without modifying the original"]
pub fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
let mut ret = Self::ZERO;
### key_expression/src/bip32.rs
@@ -671,7 +671,7 @@ impl RelativeDerivationPath {
new_path
}
- /// Returns the derivation path as a vector of raw BIP-0032 u32 child numbers.
+ /// Returns the derivation path as a vector of raw BIP-0032 `u32` child numbers.
/// Unhardened elements are copied as is.
/// 0x80000000 is added to the hardened elements.
///
### p2p/src/message_blockdata.rs
@@ -56,7 +56,7 @@ pub enum Inventory {
impl Inventory {
/// Returns the item value represented as a SHA256-d hash.
///
- /// Returns [None] only for [`Inventory::Error`] who's hash value is meaningless.
+ /// Returns `None` only for [`Inventory::Error`] whose hash value is meaningless.
pub fn network_hash(&self) -> Option<[u8; 32]> {
match self {
Self::Error(_) => None,
### primitives/src/script/push_bytes.rs
@@ -368,7 +368,7 @@ impl PushBytes {
#[inline]
pub fn len(&self) -> usize { self.as_bytes().len() }
- /// Returns true if the buffer contains zero bytes.
+ /// Returns `true` if the buffer contains zero bytes.
#[inline]
pub fn is_empty(&self) -> bool { self.as_bytes().is_empty() }
}
@@ -382,7 +382,7 @@ impl PushBytesBuf {
#[inline]
pub fn capacity(&self) -> usize { self.inner().capacity() }
- /// Returns true if the buffer contains zero bytes.
+ /// Returns `true` if the buffer contains zero bytes.
#[inline]
pub fn is_empty(&self) -> bool { self.inner().is_empty() }
}
### primitives/src/transaction.rs
@@ -1267,7 +1267,7 @@ impl Version {
#[inline]
pub const fn to_u32(self) -> u32 { self.0 }
- /// Returns true if this transaction version number is considered standard.
+ /// Returns `true` if this transaction version number is considered standard.
///
/// The behavior of this method matches whatever Bitcoin Core considers standard at the time
/// of the release and may change in future versions to accommodate new standard versions.
### units/src/amount/error.rs
@@ -136,16 +136,16 @@ impl OutOfRangeError {
}
}
- /// Returns true if the type that was attempted to be parsed is signed (`SignedAmount`).
+ /// Returns `true` if the type that was attempted to be parsed is signed (`SignedAmount`).
///
/// This can be used to hint to users to enter non-negative values specifically.
pub fn is_signed(&self) -> bool { self.is_signed }
- /// Returns true if the input value was larger than the maximum allowed value.
+ /// Returns `true` if the input value was larger than the maximum allowed value.
#[inline]
pub fn is_above_max(&self) -> bool { self.is_greater_than_max }
- /// Returns true if the input value was smaller than the minimum allowed value.
+ /// Returns `true` if the input value was smaller than the minimum allowed value.
#[inline]
pub fn is_below_min(&self) -> bool { !self.is_greater_than_max }
### units/src/locktime/absolute/mod.rs
@@ -243,7 +243,8 @@ impl LockTime {
Ok(Self::Seconds(time))
}
- /// Returns true if both lock times use the same unit i.e., both height based or both time based.
+ /// Returns `true` if both lock times use the same unit i.e., both height based or both time
+ /// based.
#[inline]
pub const fn is_same_unit(self, other: Self) -> bool {
matches!(
@@ -252,15 +253,15 @@ impl LockTime {
)
}
- /// Returns true if this lock time value is a block height.
+ /// Returns `true` if this lock time value is a block height.
#[inline]
pub const fn is_block_height(self) -> bool { matches!(self, Self::Blocks(_)) }
- /// Returns true if this lock time value is a block time (UNIX timestamp).
+ /// Returns `true` if this lock time value is a block time (UNIX timestamp).
#[inline]
pub const fn is_block_time(self) -> bool { !self.is_block_height() }
- /// Returns true if this timelock constraint is satisfied by the respective `height`/`time`.
+ /// Returns `true` if this timelock constraint is satisfied by the respective `height`/`time`.
///
/// If `self` is a blockheight based lock then it is checked against `height` and if `self` is a
/// blocktime based lock it is checked against `time`.
@@ -300,7 +301,7 @@ impl LockTime {
}
}
- /// Returns true if a transaction with this locktime can be spent in the next block.
+ /// Returns `true` if a transaction with this locktime can be spent in the next block.
///
/// If `height` is the current block height of the chain then a transaction with this locktime
/// can be broadcast for inclusion in the next block.
@@ -317,7 +318,7 @@ impl LockTime {
}
}
- /// Returns true if a transaction with this locktime can be included in the next block.
+ /// Returns `true` if a transaction with this locktime can be included in the next block.
///
/// # Errors
///
@@ -330,7 +331,7 @@ impl LockTime {
}
}
- /// Returns true if satisfaction of `other` lock time implies satisfaction of this
+ /// Returns `true` if satisfaction of `other` lock time implies satisfaction of this
/// [`absolute::LockTime`].
///
/// A lock time can only be satisfied by n blocks being mined or n seconds passing. If you have
@@ -577,7 +578,7 @@ impl Height {
#[inline]
pub const fn to_u32(self) -> u32 { self.0 }
- /// Returns true if a transaction with this locktime can be included in the next block.
+ /// Returns `true` if a transaction with this locktime can be included in the next block.
///
/// `self` is value of the [`LockTime`] and if `height` is the current chain tip then
/// a transaction with this lock can be broadcast for inclusion in the next block.
@@ -721,7 +722,7 @@ impl MedianTimePast {
#[inline]
pub const fn to_u32(self) -> u32 { self.0 }
- /// Returns true if a transaction with this locktime can be included in the next block.
+ /// Returns `true` if a transaction with this locktime can be included in the next block.
///
/// `self` is the value of the [`LockTime`] and if `time` is the median time past of the block
/// at the chain tip then a transaction with this lock can be broadcast for inclusion in the
@@ -774,11 +775,11 @@ impl<'de> Deserialize<'de> for MedianTimePast {
}
}
-/// Returns true if `n` is a block height i.e., less than 500,000,000.
+/// Returns `true` if `n` is a block height i.e., less than 500,000,000.
#[inline]
pub const fn is_block_height(n: u32) -> bool { n < LOCK_TIME_THRESHOLD }
-/// Returns true if `n` is a UNIX timestamp i.e., greater than or equal to 500,000,000.
+/// Returns `true` if `n` is a UNIX timestamp i.e., greater than or equal to 500,000,000.
#[inline]
pub const fn is_block_time(n: u32) -> bool { n >= LOCK_TIME_THRESHOLD }
### units/src/locktime/relative/mod.rs
@@ -186,21 +186,22 @@ impl LockTime {
}
}
- /// Returns true if both lock times use the same unit i.e., both height based or both time based.
+ /// Returns `true` if both lock times use the same unit i.e., both height based or both time
+ /// based.
#[inline]
pub const fn is_same_unit(self, other: Self) -> bool {
matches!((self, other), (Self::Blocks(_), Self::Blocks(_)) | (Self::Time(_), Self::Time(_)))
}
- /// Returns true if this lock time value is in units of blocks.
+ /// Returns `true` if this lock time value is in units of blocks.
#[inline]
pub const fn is_block_count(self) -> bool { matches!(self, Self::Blocks(_)) }
- /// Returns true if this lock time value is in units of time.
+ /// Returns `true` if this lock time value is in units of time.
#[inline]
pub const fn is_block_time(self) -> bool { !self.is_block_count() }
- /// Returns true if this [`relative::LockTime`] is satisfied by the given chain state.
+ /// Returns `true` if this [`relative::LockTime`] is satisfied by the given chain state.
///
/// If this function returns true then an output with this locktime can be spent in the next
/// block.
@@ -233,7 +234,7 @@ impl LockTime {
}
}
- /// Returns true if an output with this locktime can be spent in the next block.
+ /// Returns `true` if an output with this locktime can be spent in the next block.
///
/// # Arguments
///
@@ -258,7 +259,7 @@ impl LockTime {
}
}
- /// Returns true if an output with this locktime can be spent in the next block.
+ /// Returns `true` if an output with this locktime can be spent in the next block.
///
/// # Arguments
///
@@ -283,7 +284,7 @@ impl LockTime {
}
}
- /// Returns true if satisfaction of `other` lock time implies satisfaction of this
+ /// Returns `true` if satisfaction of `other` lock time implies satisfaction of this
/// [`relative::LockTime`].
///
/// A lock time can only be satisfied by n blocks being mined or n seconds passing. If you have
@@ -322,7 +323,8 @@ impl LockTime {
}
}
- /// Returns true if satisfaction of the sequence number implies satisfaction of this lock time.
+ /// Returns `true` if satisfaction of the sequence number implies satisfaction of this lock
+ /// time.
///
/// When deciding whether an instance of `<n> CHECKSEQUENCEVERIFY` will pass, this
/// method can be used by parsing `n` as a [`LockTime`] and calling this method
@@ -456,7 +458,7 @@ impl NumberOfBlocks {
Ok(Self::from_count(block_count))
}
- /// Returns true if an output locked by a block count can be spent in the next block.
+ /// Returns `true` if an output locked by a block count can be spent in the next block.
///
/// `chain_tip` can be any height from the block prior to `utxo_mined_at` onwards i.e., we
/// support a pair of parent/child transactions going into the mempool at the same time.
@@ -609,7 +611,7 @@ impl NumberOf512Seconds {
Ok(Self::from_512_second_intervals(block_count))
}
- /// Returns true if an output locked by time can be spent in the next block.
+ /// Returns `true` if an output locked by time can be spent in the next block.
///
/// # Arguments
///
### units/src/sequence.rs
@@ -103,7 +103,7 @@ impl Sequence {
#[inline]
pub fn is_final(self) -> bool { !self.enables_absolute_lock_time() }
- /// Returns true if the transaction opted-in to BIP-0125 replace-by-fee.
+ /// Returns `true` if the transaction opted-in to BIP-0125 replace-by-fee.
///
/// Replace by fee is signaled by the sequence being less than 0xfffffffe which is checked by
/// this method. Note, this is the highest "non-final" value (see [`Sequence::is_final`]).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.