Merge rust-bitcoin/rust-bitcoin#6732: primitives: Doc links follow-up
What changed, and why it matters
This commit only changes documentation comments and deprecation note formatting in the rust-bitcoin library. It replaces some inline Markdown-style links with separate reference-style link definitions, adds missing punctuation, and removes link brackets from a deprecation note. There are no code logic, API, or behavior changes, so it has no security impact.
No security action needed. This is a documentation-only cleanup; routine review/merge is sufficient.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff is limited to rustdoc comment cleanups in primitives/src/block.rs, hex_codec.rs, lib.rs, opcodes.rs, script/borrowed.rs, script/owned.rs, and transaction.rs. Changes include converting [Type](path) inline links to [Type] with a separate [Type]: path reference, adding full stops to method doc lines, and removing link syntax from a #[deprecated] note. No executable code, type definitions, trait implementations, serialization logic, or public APIs were modified.
Changed components
primitives/src/block.rsprimitives/src/hex_codec.rsprimitives/src/lib.rsprimitives/src/opcodes.rsprimitives/src/script/borrowed.rsprimitives/src/script/owned.rsprimitives/src/transaction.rsInspect captured patch +50 / −22
### primitives/src/block.rs
@@ -781,7 +781,9 @@ pub mod error {
#[doc(inline)]
pub use crate::hash_types::BlockHashDecoderError;
- /// An error consensus decoding a [`Block`](super::Block).
+ /// An error consensus decoding a [`Block`].
+ ///
+ /// [`Block`]: super::Block
#[cfg(feature = "alloc")]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BlockDecoderError(pub(super) <super::BlockInnerDecoder as encoding::Decoder>::Error);
@@ -851,7 +853,9 @@ pub mod error {
}
}
- /// An error consensus decoding a [`Header`](super::Header).
+ /// An error consensus decoding a [`Header`].
+ ///
+ /// [`Header`]: super::Header
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum HeaderDecoderError {
@@ -900,7 +904,9 @@ pub mod error {
}
}
- /// An error consensus decoding a [`Version`](super::Version).
+ /// An error consensus decoding a [`Version`].
+ ///
+ /// [`Version`]: super::Version
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VersionDecoderError(pub(super) encoding::UnexpectedEofError);
### primitives/src/hex_codec.rs
@@ -5,7 +5,9 @@
//! Various types in primitives need to be rendered in hexadecimal.
//! Since `consensus_encoding` only provides a method using `alloc`
//! to do this, this module provides utilities for alloc-less encoding
-//! of [`Encode`](encoding::Encode) types within the primitives crate.
+//! of [`Encode`] types within the primitives crate.
+//!
+//! [`Encode`]: encoding::Encode
use core::fmt;
use core::fmt::Write as _;
### primitives/src/lib.rs
@@ -93,7 +93,7 @@ pub use units::{
weight::{self, Weight},
};
-#[deprecated(since = "1.0.0-rc.0", note = "use [`BlockHeightInterval`] instead")]
+#[deprecated(since = "1.0.0-rc.0", note = "use `BlockHeightInterval` instead")]
#[doc(hidden)]
pub type BlockInterval = BlockHeightInterval;
### primitives/src/opcodes.rs
@@ -55,10 +55,12 @@ macro_rules! all_opcodes {
/// Enables wildcard imports to bring into scope all opcodes and nothing else.
///
/// The `all` module is provided so one can use a wildcard import `use primitives::opcodes::all::*`
- /// to get all the `OP_FOO` opcodes without getting other types defined in `opcodes` (e.g. [`Opcode`](crate::opcodes::Opcode)).
+ /// to get all the `OP_FOO` opcodes without getting other types defined in `opcodes` (e.g. [`Opcode`]).
///
/// This module is guaranteed to never contain anything except opcode constants and all opcode
/// constants are guaranteed to begin with `OP_`.
+ ///
+ /// [`Opcode`]: crate::opcodes::Opcode
pub mod all {
use super::Opcode;
$(
### primitives/src/script/borrowed.rs
@@ -36,9 +36,9 @@ crate::transparent_newtype! {
/// # Validity
///
/// [`Script`] does not have any validity invariants - it's essentially just a marked slice of
- /// bytes. This is similar to [`Path`](std::path::Path) vs [`OsStr`](std::ffi::OsStr) where they
- /// are trivially cast-able to each-other and `Path` doesn't guarantee being a usable FS path but
- /// having a newtype still has value because of added methods, readability and basic type checking.
+ /// bytes. This is similar to [`Path`] vs [`OsStr`] where they are trivially cast-able to each-other
+ /// and `Path` doesn't guarantee being a usable FS path but having a newtype still has value because
+ /// of added methods, readability and basic type checking.
///
/// Although at least data pushes could be checked not to overflow the script, bad scripts are
/// allowed to be in a transaction (outputs just become unspendable) and there even are such
@@ -77,14 +77,16 @@ crate::transparent_newtype! {
///
/// * [CScript definition](https://github.com/bitcoin/bitcoin/blob/d492dc1cdaabdc52b0766bf4cba4bd73178325d0/src/script/script.h#L410)
///
+ /// [`Path`]: std::path::Path
+ /// [`OsStr`]: std::ffi::OsStr
#[derive(PartialOrd, Ord, PartialEq, Eq, Hash)]
pub struct Script<T>(PhantomData<T>, [u8]);
impl<T> Script<T> {
- /// Treat byte slice as [`Script`]
+ /// Treat byte slice as [`Script`].
pub const fn from_bytes(bytes: &_) -> &Self;
- /// Treat mutable byte slice as [`Script`]
+ /// Treat mutable byte slice as [`Script`].
pub fn from_bytes_mut(bytes: &mut _) -> &mut Self;
pub(crate) fn from_boxed_bytes(bytes: Box<_>) -> Box<Self>;
@@ -174,7 +176,9 @@ impl<T> Script<T> {
#[inline]
pub const fn is_empty(&self) -> bool { self.as_bytes().is_empty() }
- /// Converts a [`Box<Script>`](Box) into a [`ScriptBuf`] without copying or allocating.
+ /// Converts a [`Box<Script>`] into a [`ScriptBuf`] without copying or allocating.
+ ///
+ /// [`Box<Script>`]: Box
#[must_use]
#[inline]
pub fn into_script_buf(self: Box<Self>) -> ScriptBuf<T> {
### primitives/src/script/owned.rs
@@ -108,8 +108,10 @@ impl<T> ScriptBuf<T> {
///
/// This method reallocates if the capacity is greater than length of the script but should not
/// when they are equal. If you know beforehand that you need to create a script of exact size
- /// use [`reserve_exact`](Self::reserve_exact) before adding data to the script so that the
- /// reallocation can be avoided.
+ /// use [`reserve_exact`] before adding data to the script so that the reallocation can be
+ /// avoided.
+ ///
+ /// [`reserve_exact`]: Self::reserve_exact
#[must_use]
#[inline]
pub fn into_boxed_script(self) -> Box<Script<T>> {
@@ -140,12 +142,14 @@ impl<T> ScriptBuf<T> {
/// `self.len() + additional`. Does nothing if the capacity is already sufficient.
///
/// Note that the allocator may give the collection more space than it requests. Therefore,
- /// capacity cannot be relied upon to be precisely minimal. Prefer [`reserve`](Self::reserve)
+ /// capacity cannot be relied upon to be precisely minimal. Prefer [`reserve`]
/// if future insertions are expected.
///
/// # Panics
///
/// Panics if the new capacity exceeds `isize::MAX` bytes.
+ ///
+ /// [`reserve`]: Self::reserve
#[inline]
pub fn reserve_exact(&mut self, additional_len: usize) { self.1.reserve_exact(additional_len); }
### primitives/src/transaction.rs
@@ -775,9 +775,11 @@ pub struct TxIn {
pub sequence: Sequence,
/// Witness data: an array of byte-arrays.
/// Note that this field is *not* (de)serialized with the rest of the [`TxIn`] in
- /// [`Encode`](encoding::Encode)/[`Decode`](encoding::Decode), as it is (de)serialized at the
- /// end of the full [`Transaction`]. It *is* (de)serialized with the rest of the [`TxIn`] in
- /// other (de)serialization routines.
+ /// [`Encode`]/[`Decode`], as it is (de)serialized at the end of the full [`Transaction`].
+ /// It *is* (de)serialized with the rest of the [`TxIn`] in other (de)serialization routines.
+ ///
+ /// [`Encode`]: encoding::Encode
+ /// [`Decode`]: encoding::Decode
pub witness: Witness,
}
@@ -1275,7 +1277,9 @@ pub mod error {
#[cfg(feature = "alloc")]
use crate::witness::WitnessDecoderError;
- /// An error consensus decoding a [`Transaction`](super::Transaction).
+ /// An error consensus decoding a [`Transaction`].
+ ///
+ /// [`Transaction`]: super::Transaction
#[cfg(feature = "alloc")]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TransactionDecoderError(pub(super) TransactionDecoderErrorInner);
@@ -1375,7 +1379,9 @@ pub mod error {
}
}
- /// An error consensus decoding a [`TxIn`](super::TxIn).
+ /// An error consensus decoding a [`TxIn`].
+ ///
+ /// [`TxIn`]: super::TxIn
#[cfg(feature = "alloc")]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TxInDecoderError(pub(super) <super::TxInInnerDecoder as encoding::Decoder>::Error);
@@ -1398,7 +1404,9 @@ pub mod error {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { Some(&self.0) }
}
- /// An error consensus decoding a [`TxOut`](super::TxOut).
+ /// An error consensus decoding a [`TxOut`].
+ ///
+ /// [`TxOut`]: super::TxOut
#[cfg(feature = "alloc")]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TxOutDecoderError(pub(super) <super::TxOutInnerDecoder as encoding::Decoder>::Error);
@@ -1490,7 +1498,9 @@ pub mod error {
}
}
- /// An error consensus decoding a [`Version`](super::Version).
+ /// An error consensus decoding a [`Version`].
+ ///
+ /// [`Version`]: super::Version
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VersionDecoderError(pub(super) encoding::UnexpectedEofError);
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.