Merge rust-bitcoin/rust-bitcoin#7011: Use Returns headings only for complex return docs
What changed, and why it matters
This commit only changes documentation comments in Rust source files. It standardizes when to use '# Returns' headings versus simple 'Returns ...' sentences. No code behavior was altered, so there is no security impact.
No action required; this is a non-functional documentation change.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The commit is a documentation-only cleanup across 15 files. It removes ‘# Returns’ headings for simple return descriptions and adds them for multi-sentence return descriptions. No executable code, logic, or API signatures were modified.
Changed components
addresses/src/lib.rsbitcoin/src/blockdata/block.rsbitcoin/src/blockdata/opcodes.rsbitcoin/src/pow.rsbitcoin/src/taproot/merkle_branch/borrowed.rsbitcoin/src/taproot/merkle_branch/buf.rsbitcoin/src/taproot/mod.rsinternals/src/array_vec.rsinternals/src/u256.rsio/src/lib.rsprimitives/src/block.rsprimitives/src/hash_types/transaction_merkle_node.rsprimitives/src/hash_types/witness_merkle_node.rsprimitives/src/merkle_tree.rstaproot_primitives/src/lib.rsInspect captured patch +39 / −57
### addresses/src/lib.rs
@@ -845,9 +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() {
### bitcoin/src/blockdata/block.rs
@@ -83,9 +83,7 @@ internal_macros::define_extension_trait! {
pub trait BlockCheckedExt: sealed::Sealed {
/// Constructs a new [`Block`].
///
- /// # Returns
- ///
- /// Return the block if it is valid, `None` if not. See [`Block::validate`].
+ /// Returns the block if it is valid, `None` if not. See [`Block::validate`].
fn new_checked(
header: Header,
transactions: Vec<Transaction>,
### bitcoin/src/blockdata/opcodes.rs
@@ -401,8 +401,6 @@ crate::internal_macros::define_extension_trait! {
///
/// Does not convert `OP_FALSE` to 0. Only `1` to `OP_PUSHNUM_16` are covered.
///
- /// # Returns
- ///
/// Returns `None` if `self` is not a PUSHNUM.
#[inline]
#[must_use]
### bitcoin/src/pow.rs
@@ -163,8 +163,6 @@ internal_macros::define_extension_trait! {
/// The difficulty can only decrease or increase by a factor of 4 max on each difficulty
/// adjustment period.
///
- /// # Returns
- ///
/// In line with Bitcoin Core this function may return a target value of zero.
fn min_transition_threshold(&self) -> Self {
Self::from_inner(self.to_inner() >> 2)
@@ -302,9 +300,7 @@ internal_macros::define_extension_trait! {
///
/// To calculate the timespan, users should first convert their u32 timestamps to i64s before subtracting them
///
- /// # Returns
- ///
- /// The expected [`CompactTarget`] recalculation.
+ /// Returns the expected [`CompactTarget`] recalculation.
fn from_next_work_required(
last: CompactTarget,
timespan: i64,
@@ -346,9 +342,7 @@ internal_macros::define_extension_trait! {
/// one would pass the header for Block 2015 as `current` and the header for Block 0 as
/// `last_epoch_boundary`.
///
- /// # Returns
- ///
- /// The expected [`CompactTarget`] recalculation.
+ /// Returns the expected [`CompactTarget`] recalculation.
fn from_header_difficulty_adjustment(
last_epoch_boundary: Header,
current: Header,
### bitcoin/src/taproot/merkle_branch/borrowed.rs
@@ -69,9 +69,7 @@ impl TaprootMerkleBranch {
/// Serializes to a writer.
///
- /// # Returns
- ///
- /// The number of bytes written to the writer.
+ /// Returns the number of bytes written to the writer.
pub fn encode<Write: io::Write + ?Sized>(&self, writer: &mut Write) -> io::Result<usize> {
let bytes = self.as_bytes();
writer.write_all(bytes)?;
### bitcoin/src/taproot/merkle_branch/buf.rs
@@ -72,9 +72,7 @@ impl TaprootMerkleBranchBuf {
/// Serializes to a writer.
///
- /// # Returns
- ///
- /// The number of bytes written to the writer.
+ /// Returns the number of bytes written to the writer.
pub fn encode<Write: io::Write + ?Sized>(&self, writer: &mut Write) -> io::Result<usize> {
for hash in self {
writer.write_all(hash.as_ref())?;
### bitcoin/src/taproot/mod.rs
@@ -1065,9 +1065,7 @@ impl<Branch: AsRef<TaprootMerkleBranch> + ?Sized> ControlBlock<Branch> {
/// Serializes to a writer.
///
- /// # Returns
- ///
- /// The number of bytes written to the writer.
+ /// Returns the number of bytes written to the writer.
pub fn encode<W: Write + ?Sized>(&self, writer: &mut W) -> io::Result<usize> {
self.encode_inner(move |bytes| writer.write_all(bytes))?;
Ok(self.size())
### internals/src/array_vec.rs
@@ -274,9 +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
@@ -120,9 +120,7 @@ impl U256 {
/// Calculates quotient and remainder.
///
- /// # Returns
- ///
- /// (quotient, remainder)
+ /// Returns (quotient, remainder).
///
/// # Panics
///
@@ -165,7 +163,9 @@ impl U256 {
/// Calculates `self` + `rhs`
///
- /// Returns a tuple of the addition along with a boolean indicating whether an arithmetic
+ /// # 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.
#[must_use = "this returns the result of the operation, without modifying the original"]
pub fn overflowing_add(self, rhs: Self) -> (Self, bool) {
@@ -189,7 +189,9 @@ impl U256 {
/// Calculates `self` - `rhs`
///
- /// Returns a tuple of the subtraction along with a boolean indicating whether an arithmetic
+ /// # 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.
#[must_use = "this returns the result of the operation, without modifying the original"]
pub fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
@@ -200,7 +202,9 @@ impl U256 {
/// Calculates the multiplication of `self` and `rhs`.
///
- /// Returns a tuple of the multiplication along with a boolean
+ /// # 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.
#[must_use = "this returns the result of the operation, without modifying the original"]
### io/src/lib.rs
@@ -64,9 +64,7 @@ pub type Result<T> = core::result::Result<T, Error>;
pub trait Read {
/// Reads bytes from source into `buf`.
///
- /// # Returns
- ///
- /// The number of bytes read if successful or an [`Error`] if reading fails.
+ /// Returns the number of bytes read if successful or an [`Error`] if reading fails.
///
/// # Errors
///
@@ -107,9 +105,7 @@ pub trait Read {
///
/// Similar to [`std::io::Read::read_to_end`] but with the DOS protection.
///
- /// # Returns
- ///
- /// The number of bytes read if successful or an [`Error`] if reading fails.
+ /// Returns the number of bytes read if successful or an [`Error`] if reading fails.
///
/// # Errors
///
@@ -153,9 +149,7 @@ impl<R: Read> Take<R> {
///
/// Allocates space in `buf` as needed.
///
- /// # Returns
- ///
- /// The number of bytes read if successful or an [`Error`] if reading fails.
+ /// Returns the number of bytes read if successful or an [`Error`] if reading fails.
///
/// # Errors
///
### primitives/src/block.rs
@@ -622,7 +622,9 @@ fn block_weight_wu(transactions: &[Transaction]) -> u64 {
/// Computes the Merkle root for a list of transactions.
///
-/// Returns [`None`] if the iterator was empty, or if the transaction list contains
+/// # Returns
+///
+/// [`None`] if the iterator was empty, or if the transaction list contains
/// consecutive duplicates which would trigger CVE 2012-2459. Blocks with duplicate
/// transactions will always be invalid, so there is no harm in us refusing to
/// compute their merkle roots.
@@ -641,7 +643,9 @@ where
/// Computes the Merkle root of transactions hashed for witness.
///
-/// Returns [`None`] if the iterator was empty, or if the transaction list contains
+/// # Returns
+///
+/// [`None`] if the iterator was empty, or if the transaction list contains
/// consecutive duplicates which would trigger CVE 2012-2459. Blocks with duplicate
/// transactions will always be invalid, so there is no harm in us refusing to
/// compute their merkle roots.
### primitives/src/hash_types/transaction_merkle_node.rs
@@ -40,7 +40,9 @@ impl TxMerkleNode {
/// Given an iterator of leaves, compute the Merkle root.
///
- /// Returns [`None`] if the iterator was empty, or if the transaction list contains
+ /// # Returns
+ ///
+ /// [`None`] if the iterator was empty, or if the transaction list contains
/// consecutive duplicates which would trigger CVE 2012-2459. Blocks with duplicate
/// transactions will always be invalid, so there is no harm in us refusing to
/// compute their merkle roots.
### primitives/src/hash_types/witness_merkle_node.rs
@@ -40,7 +40,9 @@ impl WitnessMerkleNode {
/// Given an iterator of leaves, compute the Merkle root.
///
- /// Returns [`None`] if the iterator was empty, or if the transaction list contains
+ /// # Returns
+ ///
+ /// [`None`] if the iterator was empty, or if the transaction list contains
/// consecutive duplicates which would trigger CVE 2012-2459. Blocks with duplicate
/// transactions will always be invalid, so there is no harm in us refusing to
/// compute their merkle roots.
### primitives/src/merkle_tree.rs
@@ -47,7 +47,9 @@ pub(crate) trait MerkleNode: Copy + PartialEq {
/// Given an iterator of leaves, compute the Merkle root.
///
- /// Returns [`None`] if the iterator was empty, or if the transaction list contains
+ /// # Returns
+ ///
+ /// [`None`] if the iterator was empty, or if the transaction list contains
/// consecutive duplicates which would trigger CVE 2012-2459. Blocks with duplicate
/// transactions will always be invalid, so there is no harm in us refusing to
/// compute their merkle roots.
### taproot_primitives/src/lib.rs
@@ -369,9 +369,7 @@ pub trait TapTweak {
/// * c is the commitment data
/// * G is the generator point
///
- /// # Returns
- ///
- /// The tweaked key, with the required parity.
+ /// Returns the tweaked key, with the required parity.
///
/// [`Keypair`]: crypto::Keypair
fn tap_tweak(&self, merkle_root: Option<TapNodeHash>) -> Self::TweakedAux;
@@ -397,9 +395,7 @@ impl TapTweak for UntweakedPublicKey {
/// * c is the commitment data
/// * G is the generator point
///
- /// # Returns
- ///
- /// The tweaked key and its parity.
+ /// Returns the tweaked key and its parity.
fn tap_tweak(&self, merkle_root: Option<TapNodeHash>) -> TweakedPublicKey {
let tweak = TapTweakHash::from_key_and_merkle_root(*self, merkle_root).to_scalar();
let output_key = self.add_tweak(&tweak).expect("Tap tweak failed");
@@ -424,9 +420,7 @@ impl TapTweak for UntweakedKeypair {
/// a Taproot key which can [provably only be spent via
/// keyspend](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki#cite_note-23).
///
- /// # Returns
- ///
- /// The tweaked keypair.
+ /// Returns the tweaked keypair.
fn tap_tweak(&self, merkle_root: Option<TapNodeHash>) -> TweakedKeypair {
let pubkey = XOnlyPublicKey::from_keypair(self);
let tweak = TapTweakHash::from_key_and_merkle_root(pubkey, merkle_root).to_scalar();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.