consensus_encoding: Set 100 column width
What changed, and why it matters
This commit only reformats documentation comments (rustdoc) in five source files to match the project's preferred 100-column line width. No executable code, logic, or behavior was changed. It is a cosmetic/style-only change with no security relevance.
No action required. This is a documentation formatting commit and can be treated as routine maintenance.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff consists entirely of line-wrapping adjustments to //! and /// doc comments in consensus_encoding/src/compact_size.rs, decode/mod.rs, encode/encoders.rs, encode/mod.rs, and lib.rs. There are no changes to function bodies, signatures, trait implementations, control flow, constants, or public APIs. The one minor non-whitespace edit is splitting a single sentence in encode/mod.rs (May return an empty list. moved to its own line), which remains a documentation-only change.
Changed components
consensus_encoding/src/compact_size.rsconsensus_encoding/src/decode/mod.rsconsensus_encoding/src/encode/encoders.rsconsensus_encoding/src/encode/mod.rsconsensus_encoding/src/lib.rsInspect captured patch +109 / −129
diff --git a/consensus_encoding/src/compact_size.rs b/consensus_encoding/src/compact_size.rs
index 47df41b5..824720b7 100644
--- a/consensus_encoding/src/compact_size.rs
+++ b/consensus_encoding/src/compact_size.rs
@@ -2,9 +2,9 @@
//! Compact size codec.
//!
-//! Compact size is a variable-length integer encoding used throughout the
-//! Bitcoin consensus protocol to usually to encode collection lengths. However,
-//! there are also some unique non-length use cases.
+//! Compact size is a variable-length integer encoding used throughout the Bitcoin
+//! consensus protocol to usually to encode collection lengths. However, there are
+//! also some unique non-length use cases.
use core::convert::Infallible;
@@ -38,18 +38,16 @@ pub struct CompactSizeEncoder {
impl CompactSizeEncoder {
/// Constructs a new `CompactSizeEncoder` for a length prefix.
///
- /// The `usize` type is the natural Rust type for lengths and collection sizes,
- /// which is the dominant use case for compact size encoding in the Bitcoin
- /// protocol. Prefer this constructor whenever you are encoding the length of
- /// a collection or a byte slice.
+ /// The `usize` type is the natural Rust type for lengths and collection sizes, which is the
+ /// dominant use case for compact size encoding in the Bitcoin protocol. Prefer this constructor
+ /// whenever you are encoding the length of a collection or a byte slice.
///
- /// Compact size encodings are defined only over the `u64` range. On exotic
- /// platforms where `usize` is wider than 64 bits the value will be saturated
- /// to [`u64::MAX`], but in practice any in-memory length that could actually
- /// be passed here is well within the `u64` range.
+ /// Compact size encodings are defined only over the `u64` range. On exotic platforms where
+ /// `usize` is wider than 64 bits the value will be saturated to [`u64::MAX`], but in practice
+ /// any in-memory length that could actually be passed here is well within the `u64` range.
///
- /// If you need to encode an arbitrary `u64` integer that is not a length
- /// prefix, use [`Self::new_u64`] instead.
+ /// If you need to encode an arbitrary `u64` integer that is not a length prefix, use
+ /// [`Self::new_u64`] instead.
pub fn new(value: usize) -> Self {
Self { buf: Some(Self::encode(u64::try_from(value).unwrap_or(u64::MAX))) }
}
@@ -58,10 +56,9 @@ impl CompactSizeEncoder {
///
/// Prefer [`Self::new`] unless you are encoding a non-length integer.
///
- /// A small number of fields in the Bitcoin protocol are compact-size-encoded
- /// integers that are not collection lengths (e.g. service flags). Use this
- /// constructor for those cases, where the natural type of the value is `u64`
- /// rather than `usize`.
+ /// A small number of fields in the Bitcoin protocol are compact-size-encoded integers that are
+ /// not collection lengths (e.g. service flags). Use this constructor for those cases, where the
+ /// natural type of the value is `u64` rather than `usize`.
pub fn new_u64(value: u64) -> Self { Self { buf: Some(Self::encode(value)) } }
/// Returns the number of bytes used to encode this `CompactSize` value.
@@ -127,15 +124,14 @@ impl ExactSizeEncoder for CompactSizeEncoder {
/// Decodes a compact size encoded integer as a length prefix.
///
-/// The decoded value is returned as a `usize` and is bounded by a configurable
-/// limit (default: 4,000,000). This limit is a denial-of-service protection: a
-/// malicious peer can send a compact size value up to 2^64-1, and without a
-/// limit check the caller might attempt to allocate an enormous buffer based on
-/// that value. [`CompactSizeDecoder`] prevents this by rejecting values that
-/// exceed the limit before returning them to the caller.
+/// The decoded value is returned as a `usize` and is bounded by a configurable limit (default:
+/// 4,000,000). This limit is a denial-of-service protection: a malicious peer can send a compact
+/// size value up to 2^64-1, and without a limit check the caller might attempt to allocate an
+/// enormous buffer based on that value. [`CompactSizeDecoder`] prevents this by rejecting values
+/// that exceed the limit before returning them to the caller.
///
-/// If you are decoding an arbitrary `u64` integer that is genuinely not a length
-/// prefix, use [`CompactSizeU64Decoder`] instead.
+/// If you are decoding an arbitrary `u64` integer that is genuinely not a length prefix, use
+/// [`CompactSizeU64Decoder`] instead.
///
/// For more information about decoders see the documentation of the [`Decoder`] trait.
#[derive(Debug, Clone)]
@@ -147,17 +143,16 @@ pub struct CompactSizeDecoder {
impl CompactSizeDecoder {
/// Constructs a new compact size decoder with the default length limit.
///
- /// The decoded value must not exceed 4,000,000 and must fit in a `usize`,
- /// otherwise [`end`](Self::end) will return an error. This default limit
- /// reflects the maximum sensible vector length under the 4 MB block weight
- /// limit.
+ /// The decoded value must not exceed 4,000,000 and must fit in a `usize`, otherwise
+ /// [`end`](Self::end) will return an error. This default limit reflects the maximum sensible
+ /// vector length under the 4 MB block weight limit.
pub const fn new() -> Self { Self { buf: ArrayVec::new(), limit: MAX_VEC_SIZE } }
/// Constructs a new compact size decoder with a custom length limit.
///
- /// The decoded value must not exceed `limit`, otherwise [`end`](Self::end)
- /// will return an error. Use this when you know the field you are decoding
- /// has a tighter bound than the default limit of 4,000,000.
+ /// The decoded value must not exceed `limit`, otherwise [`end`](Self::end) will return an
+ /// error. Use this when you know the field you are decoding has a tighter bound than the
+ /// default limit of 4,000,000.
pub const fn new_with_limit(limit: usize) -> Self { Self { buf: ArrayVec::new(), limit } }
}
@@ -203,19 +198,18 @@ impl Decoder for CompactSizeDecoder {
///
/// If you are decoding a length prefix, you probably want [`CompactSizeDecoder`] instead.
///
-/// This decoder performs no limit check and no conversion to `usize`. It exists
-/// for the small number of Bitcoin protocol fields that are compact-size-encoded
-/// integers but are not length prefixes (e.g. service flags in the `version`
-/// message). For those fields the full `u64` range is meaningful and there is no
-/// associated allocation whose size would be controlled by the decoded value.
+/// This decoder performs no limit check and no conversion to `usize`. It exists for the small
+/// number of Bitcoin protocol fields that are compact-size-encoded integers but are not length
+/// prefixes (e.g. service flags in the `version` message). For those fields the full `u64` range is
+/// meaningful and there is no associated allocation whose size would be controlled by the decoded
+/// value.
///
/// # Denial-of-service warning
///
-/// Do not use this decoder for length prefixes. If the decoded value is used
-/// to size an allocation, for example as the length of a `Vec`, a malicious
-/// peer can send a compact size value of up to 2^64-1 and cause an out-of-memory
-/// condition. [`CompactSizeDecoder`] prevents this by enforcing a configurable
-/// upper bound before returning the value.
+/// Do not use this decoder for length prefixes. If the decoded value is used to size an allocation,
+/// for example as the length of a `Vec`, a malicious peer can send a compact size value of up to
+/// 2^64-1 and cause an out-of-memory condition. [`CompactSizeDecoder`] prevents this by enforcing a
+/// configurable upper bound before returning the value.
///
/// For more information about decoders see the documentation of the [`Decoder`] trait.
#[derive(Debug, Clone)]
@@ -226,8 +220,8 @@ pub struct CompactSizeU64Decoder {
impl CompactSizeU64Decoder {
/// Constructs a new `CompactSizeU64Decoder`.
///
- /// See the [struct-level documentation](Self) for guidance on when to use
- /// this decoder versus [`CompactSizeDecoder`].
+ /// See the [struct-level documentation](Self) for guidance on when to use this decoder versus
+ /// [`CompactSizeDecoder`].
pub const fn new() -> Self { Self { buf: ArrayVec::new() } }
}
diff --git a/consensus_encoding/src/decode/mod.rs b/consensus_encoding/src/decode/mod.rs
index bfc416d0..b9d1a552 100644
--- a/consensus_encoding/src/decode/mod.rs
+++ b/consensus_encoding/src/decode/mod.rs
@@ -11,8 +11,8 @@ pub mod decoders;
/// A Bitcoin object which can be consensus-decoded using a push decoder.
///
-/// To decode something, create a [`Self::Decoder`] and push byte slices
-/// into it with [`Decoder::push_bytes`], then call [`Decoder::end`] to get the result.
+/// To decode something, create a [`Self::Decoder`] and push byte slices into it with
+/// [`Decoder::push_bytes`], then call [`Decoder::end`] to get the result.
///
/// # Examples
///
@@ -59,17 +59,16 @@ pub trait Decoder: Sized {
/// Pushes bytes into the decoder, consuming as much as possible.
///
- /// The slice reference will be advanced to point to the unconsumed portion.
- /// Returns `Ok(true)` if more bytes are needed to complete decoding,
- /// `Ok(false)` if the decoder is ready to finalize with [`Self::end`],
- /// or `Err(error)` if parsing failed.
+ /// The slice reference will be advanced to point to the unconsumed portion. Returns `Ok(true)`
+ /// if more bytes are needed to complete decoding, `Ok(false)` if the decoder is ready to
+ /// finalize with [`Self::end`], or `Err(error)` if parsing failed.
///
/// # Errors
///
- /// Returns an error if the provided bytes are invalid or malformed according
- /// to the decoder's validation rules. Insufficient data (needing more
- /// bytes) is *not* an error for this method, the decoder will simply consume
- /// what it can and return `true` to indicate more data is needed.
+ /// Returns an error if the provided bytes are invalid or malformed according to the decoder's
+ /// validation rules. Insufficient data (needing more bytes) is *not* an error for this method,
+ /// the decoder will simply consume what it can and return `true` to indicate more data is
+ /// needed.
///
/// # Panics
///
@@ -80,14 +79,12 @@ pub trait Decoder: Sized {
/// Completes the decoding process and return the final result.
///
- /// This consumes the decoder and should be called when no more input
- /// data is available.
+ /// This consumes the decoder and should be called when no more input data is available.
///
/// # Errors
///
- /// Returns an error if the decoder has not received sufficient data to
- /// complete decoding, or if the accumulated data is invalid when considered
- /// as a complete object.
+ /// Returns an error if the decoder has not received sufficient data to complete decoding, or if
+ /// the accumulated data is invalid when considered as a complete object.
///
/// # Panics
///
@@ -98,9 +95,9 @@ pub trait Decoder: Sized {
/// Returns the maximum number of bytes this decoder can consume without over-reading.
///
- /// Returns 0 if the decoder is complete and ready to finalize with [`Self::end`].
- /// This is used by [`decode_from_read_unbuffered`] to optimize read sizes,
- /// avoiding both inefficient under-reads and unnecessary over-reads.
+ /// Returns 0 if the decoder is complete and ready to finalize with [`Self::end`]. This is used
+ /// by [`decode_from_read_unbuffered`] to optimize read sizes, avoiding both inefficient
+ /// under-reads and unnecessary over-reads.
fn read_limit(&self) -> usize;
}
@@ -108,9 +105,8 @@ pub trait Decoder: Sized {
///
/// # Errors
///
-/// Returns an error if the decoder encounters an error while
-/// parsing the data, including insufficient data. This function
-/// also errors if the provided slice is not completely consumed
+/// Returns an error if the decoder encounters an error while parsing the data, including
+/// insufficient data. This function also errors if the provided slice is not completely consumed
/// during decode.
pub fn decode_from_slice<T: Decodable>(
bytes: &[u8],
@@ -127,15 +123,14 @@ pub fn decode_from_slice<T: Decodable>(
/// Decodes an object from an unbounded byte slice.
///
-/// Unlike [`decode_from_slice`], this function will not error if the slice
-/// contains additional bytes that are not required to decode.
-/// Furthermore, the byte slice reference provided to this function will be
-/// updated based on the consumed data, returning the unconsumed bytes.
+/// Unlike [`decode_from_slice`], this function will not error if the slice contains additional
+/// bytes that are not required to decode. Furthermore, the byte slice reference provided to this
+/// function will be updated based on the consumed data, returning the unconsumed bytes.
///
/// # Errors
///
-/// Returns an error if the decoder encounters an error while
-/// parsing the data, including insufficient data.
+/// Returns an error if the decoder encounters an error while parsing the data, including
+/// insufficient data.
pub fn decode_from_slice_unbounded<T>(
bytes: &mut &[u8],
) -> Result<T, <T::Decoder as Decoder>::Error>
@@ -157,15 +152,14 @@ where
///
/// # Performance
///
-/// For unbuffered readers (like [`std::fs::File`] or [`std::net::TcpStream`]),
-/// consider wrapping your reader with [`std::io::BufReader`] in order to use
-/// this function. This avoids frequent small reads, which can significantly
-/// impact performance.
+/// For unbuffered readers (like [`std::fs::File`] or [`std::net::TcpStream`]), consider wrapping
+/// your reader with [`std::io::BufReader`] in order to use this function. This avoids frequent
+/// small reads, which can significantly impact performance.
///
/// # Errors
///
-/// Returns [`ReadError::Decode`] if the decoder encounters an error while parsing
-/// the data, or [`ReadError::Io`] if an I/O error occurs while reading.
+/// Returns [`ReadError::Decode`] if the decoder encounters an error while parsing the data, or
+/// [`ReadError::Io`] if an I/O error occurs while reading.
#[cfg(feature = "std")]
pub fn decode_from_read<T, R>(mut reader: R) -> Result<T, ReadError<<T::Decoder as Decoder>::Error>>
where
@@ -200,22 +194,21 @@ where
/// Decodes an object from an unbuffered reader using a fixed-size buffer.
///
-/// For most use cases, prefer [`decode_from_read`] with a [`std::io::BufReader`].
-/// This function is only needed when you have an unbuffered reader which you
-/// cannot wrap. It will probably have worse performance.
+/// For most use cases, prefer [`decode_from_read`] with a [`std::io::BufReader`]. This function is
+/// only needed when you have an unbuffered reader which you cannot wrap. It will probably have
+/// worse performance.
///
/// # Buffer
///
-/// Uses a fixed 4KB (4096 bytes) stack-allocated buffer that is reused across
-/// read operations. This size is a good balance between memory usage and
-/// system call efficiency for most use cases.
+/// Uses a fixed 4KB (4096 bytes) stack-allocated buffer that is reused across read operations. This
+/// size is a good balance between memory usage and system call efficiency for most use cases.
///
/// For different buffer sizes, use [`decode_from_read_unbuffered_with`].
///
/// # Errors
///
-/// Returns [`ReadError::Decode`] if the decoder encounters an error while parsing
-/// the data, or [`ReadError::Io`] if an I/O error occurs while reading.
+/// Returns [`ReadError::Decode`] if the decoder encounters an error while parsing the data, or
+/// [`ReadError::Io`] if an I/O error occurs while reading.
#[cfg(feature = "std")]
pub fn decode_from_read_unbuffered<T, R>(
reader: R,
@@ -229,21 +222,20 @@ where
/// Decodes an object from an unbuffered reader using a custom-sized buffer.
///
-/// For most use cases, prefer [`decode_from_read`] with a [`std::io::BufReader`].
-/// This function is only needed when you have an unbuffered reader which you
-/// cannot wrap. It will probably have worse performance.
+/// For most use cases, prefer [`decode_from_read`] with a [`std::io::BufReader`]. This function is
+/// only needed when you have an unbuffered reader which you cannot wrap. It will probably have
+/// worse performance.
///
/// # Buffer
///
-/// The `BUFFER_SIZE` parameter controls the intermediate buffer size used for
-/// reading. The buffer is allocated on the stack (not heap) and reused across
-/// read operations. Larger buffers reduce the number of system calls, but use
-/// more memory.
+/// The `BUFFER_SIZE` parameter controls the intermediate buffer size used for reading. The buffer
+/// is allocated on the stack (not heap) and reused across read operations. Larger buffers reduce
+/// the number of system calls, but use more memory.
///
/// # Errors
///
-/// Returns [`ReadError::Decode`] if the decoder encounters an error while parsing
-/// the data, or [`ReadError::Io`] if an I/O error occurs while reading.
+/// Returns [`ReadError::Decode`] if the decoder encounters an error while parsing the data, or
+/// [`ReadError::Io`] if an I/O error occurs while reading.
#[cfg(feature = "std")]
pub fn decode_from_read_unbuffered_with<T, R, const BUFFER_SIZE: usize>(
mut reader: R,
diff --git a/consensus_encoding/src/encode/encoders.rs b/consensus_encoding/src/encode/encoders.rs
index d914d1cb..9bfe3255 100644
--- a/consensus_encoding/src/encode/encoders.rs
+++ b/consensus_encoding/src/encode/encoders.rs
@@ -2,11 +2,10 @@
//! Collection of "standard encoders".
//!
-//! These encoders should not be used directly. Instead, when implementing the
-//! [`super::Encodable`] trait on a type, you should define a newtype around one
-//! or more of these encoders, and pass through the [`Encoder`] implementation
-//! to your newtype. This avoids leaking encoding implementation details to the
-//! users of your type.
+//! These encoders should not be used directly. Instead, when implementing the [`super::Encodable`]
+//! trait on a type, you should define a newtype around one or more of these encoders, and pass
+//! through the [`Encoder`] implementation to your newtype. This avoids leaking encoding
+//! implementation details to the users of your type.
//!
//! For implementing these newtypes, we provide the [`encoder_newtype`] and
//! [`encoder_newtype_exact`] macros.
diff --git a/consensus_encoding/src/encode/mod.rs b/consensus_encoding/src/encode/mod.rs
index 8363a7f8..dec01aa4 100644
--- a/consensus_encoding/src/encode/mod.rs
+++ b/consensus_encoding/src/encode/mod.rs
@@ -9,9 +9,8 @@ pub mod encoders;
/// A Bitcoin object which can be consensus-encoded.
///
-/// To encode something, use the [`Self::encoder`] method to obtain a
-/// [`Self::Encoder`], which will behave like an iterator yielding
-/// byte slices.
+/// To encode something, use the [`Self::encoder`] method to obtain a [`Self::Encoder`], which will
+/// behave like an iterator yielding byte slices.
///
/// # Examples
///
@@ -52,8 +51,8 @@ pub trait Encodable {
pub trait Encoder {
/// Yields the current encoded byteslice.
///
- /// Will always return the same value until [`Self::advance`] is called. May return an empty
- /// list.
+ /// Will always return the same value until [`Self::advance`] is called.
+ /// May return an empty list.
fn current_chunk(&self) -> &[u8];
/// Moves the encoder to its next state.
@@ -205,10 +204,9 @@ where
///
/// # Performance
///
-/// This method writes data in potentially small chunks based on the encoder's
-/// internal chunking strategy. For optimal performance with unbuffered writers
-/// (like [`std::fs::File`] or [`std::net::TcpStream`]), consider wrapping your
-/// writer with [`std::io::BufWriter`].
+/// This method writes data in potentially small chunks based on the encoder's internal chunking
+/// strategy. For optimal performance with unbuffered writers (like [`std::fs::File`] or
+/// [`std::net::TcpStream`]), consider wrapping your writer with [`std::io::BufWriter`].
///
/// # Errors
///
diff --git a/consensus_encoding/src/lib.rs b/consensus_encoding/src/lib.rs
index 5cf3280c..c8d634f2 100644
--- a/consensus_encoding/src/lib.rs
+++ b/consensus_encoding/src/lib.rs
@@ -2,36 +2,33 @@
//! # Rust Bitcoin Consensus Encoding
//!
-//! Traits and utilities for encoding and decoding Bitcoin data types in a
-//! consensus-consistent way, using a *sans-I/O* architecture.
+//! Traits and utilities for encoding and decoding Bitcoin data types in a consensus-consistent way,
+//! using a *sans-I/O* architecture.
//!
-//! Rather than reading from or writing to [`std::io::Read`]/[`std::io::Write`]
-//! traits directly, the codec types work with byte slices. This keeps codec logic
-//! I/O-agnostic, so the same implementation works in `no_std` environments, sync
-//! I/O, async I/O, and hash engines without duplicating logic or surfacing
-//! I/O errors in non-I/O contexts (e.g. when hashing an encoding).
+//! Rather than reading from or writing to [`std::io::Read`]/[`std::io::Write`] traits directly, the
+//! codec types work with byte slices. This keeps codec logic I/O-agnostic, so the same
+//! implementation works in `no_std` environments, sync I/O, async I/O, and hash engines without
+//! duplicating logic or surfacing I/O errors in non-I/O contexts (e.g. when hashing an encoding).
//!
-//! *Consensus* encoding is the canonical byte representation of Bitcoin data
-//! types used across the peer-to-peer network and transaction serialization.
-//! This crate only supports deterministic encoding and will never support
-//! types like floats whose encoding is non-deterministic or platform-dependent.
+//! *Consensus* encoding is the canonical byte representation of Bitcoin data types used across the
+//! peer-to-peer network and transaction serialization. This crate only supports deterministic
+//! encoding and will never support types like floats whose encoding is non-deterministic or
+//! platform-dependent.
//!
//! # Encoding
//!
-//! Types implement [`Encodable`] to produce an [`Encoder`], which yields encoded
-//! bytes in chunks via [`Encoder::current_chunk`] and [`Encoder::advance`]. The
-//! caller drives the process by pulling chunks until `advance` returns `false`.
+//! Types implement [`Encodable`] to produce an [`Encoder`], which yields encoded bytes in chunks
+//! via [`Encoder::current_chunk`] and [`Encoder::advance`]. The caller drives the process by
+//! pulling chunks until `advance` returns `false`.
//!
//! # Decoding
//!
-//! Types implement [`Decodable`] to produce a [`Decoder`], which consumes bytes
-//! via [`Decoder::push_bytes`] until it signals completion by returning
-//! `Ok(false)`. The caller then calls [`Decoder::end`] to obtain the decoded
-//! value.
+//! Types implement [`Decodable`] to produce a [`Decoder`], which consumes bytes via
+//! [`Decoder::push_bytes`] until it signals completion by returning `Ok(false)`. The caller then
+//! calls [`Decoder::end`] to obtain the decoded value.
//!
-//! Unlike encoding, decoding is fallible. Both `push_bytes` and `end` return
-//! `Result`. I/O errors are handled by the caller, keeping the codec logic
-//! I/O-agnostic.
+//! Unlike encoding, decoding is fallible. Both `push_bytes` and `end` return `Result`. I/O errors
+//! are handled by the caller, keeping the codec logic I/O-agnostic.
//!
//! # Drivers
//!
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.