From b844637935f7725e80a4e32d5ea8c9ff3c2be3f1 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Tue, 7 Jan 2025 17:16:24 +1100 Subject: [PATCH 1/5] io: Remove rustdoc for private module This doc adds little value and has typos in it - just remove it. --- io/src/macros.rs | 2 -- 1 file changed, 2 deletions(-) diff --git a/io/src/macros.rs b/io/src/macros.rs index 5fae2a750..a0ed86576 100644 --- a/io/src/macros.rs +++ b/io/src/macros.rs @@ -1,5 +1,3 @@ -//! Public macros for porvide.d for users to be able implement our `io::Write` trait. - #[macro_export] /// Because we cannot provide a blanket implementation of [`std::io::Write`] for all implementers /// of this crate's `io::Write` trait, we provide this macro instead. From 07d8703a00b5e3721f1dcdb141cf6bc606351df5 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Tue, 7 Jan 2025 09:21:57 +1100 Subject: [PATCH 2/5] io: Add SPDX identifier The `io` crate is licensed in the manifest using the CC0-1.0 license same as the rest of the codebase but none of the individual files have a license blurb. Add a CC0-1.0 license blurb by way of an SPDX-License-Identifier tag. --- io/src/bridge.rs | 2 ++ io/src/error.rs | 2 ++ io/src/lib.rs | 2 ++ io/src/macros.rs | 2 ++ 4 files changed, 8 insertions(+) diff --git a/io/src/bridge.rs b/io/src/bridge.rs index 4079d57fd..fc49a0771 100644 --- a/io/src/bridge.rs +++ b/io/src/bridge.rs @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: CC0-1.0 + #[cfg(feature = "alloc")] use alloc::boxed::Box; diff --git a/io/src/error.rs b/io/src/error.rs index 172dd3d6a..6ae9719bd 100644 --- a/io/src/error.rs +++ b/io/src/error.rs @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: CC0-1.0 + #[cfg(all(not(feature = "std"), feature = "alloc"))] use alloc::boxed::Box; use core::fmt; diff --git a/io/src/lib.rs b/io/src/lib.rs index ffb2af0de..f501ad46e 100644 --- a/io/src/lib.rs +++ b/io/src/lib.rs @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: CC0-1.0 + //! Rust-Bitcoin I/O Library //! //! The `std::io` module is not exposed in `no-std` Rust so building `no-std` applications which diff --git a/io/src/macros.rs b/io/src/macros.rs index a0ed86576..4904a826d 100644 --- a/io/src/macros.rs +++ b/io/src/macros.rs @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: CC0-1.0 + #[macro_export] /// Because we cannot provide a blanket implementation of [`std::io::Write`] for all implementers /// of this crate's `io::Write` trait, we provide this macro instead. From b109177e116d83872e38321675525567e7d22b6f Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Tue, 7 Jan 2025 10:35:24 +1100 Subject: [PATCH 3/5] io: Improve rustdocs In preparation for releasing `io v1.0` make a sweep of the rustdocs and improve them for all modules except `macros`. With this applied I believe we can tick off: - C-FAILURE - C-LINK - C-HIDDEN --- io/src/lib.rs | 44 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 36 insertions(+), 8 deletions(-) diff --git a/io/src/lib.rs b/io/src/lib.rs index f501ad46e..1605300ea 100644 --- a/io/src/lib.rs +++ b/io/src/lib.rs @@ -2,9 +2,9 @@ //! Rust-Bitcoin I/O Library //! -//! The `std::io` module is not exposed in `no-std` Rust so building `no-std` applications which +//! The [`std::io`] module is not exposed in `no-std` Rust so building `no-std` applications which //! require reading and writing objects via standard traits is not generally possible. Thus, this -//! library exists to export a minmal version of `std::io`'s traits which we use in `rust-bitcoin` +//! library exists to export a minimal version of `std::io`'s traits which we use in `rust-bitcoin` //! so that we can support `no-std` applications. //! //! These traits are not one-for-one drop-ins, but are as close as possible while still implementing @@ -43,12 +43,22 @@ pub use self::error::{Error, ErrorKind}; /// Result type returned by functions in this crate. pub type Result = core::result::Result; -/// A generic trait describing an input stream. See [`std::io::Read`] for more info. +/// A generic trait describing an input stream. +/// +/// See [`std::io::Read`] for more information. pub trait Read { /// Reads bytes from source into `buf`. + /// + /// # Returns + /// + /// The number of bytes read if successful or an [`Error`] if reading fails. fn read(&mut self, buf: &mut [u8]) -> Result; /// Reads bytes from source until `buf` is full. + /// + /// # Errors + /// + /// If the exact number of bytes required to fill `buf` cannot be read. #[inline] fn read_exact(&mut self, mut buf: &mut [u8]) -> Result<()> { while !buf.is_empty() { @@ -71,7 +81,11 @@ pub trait Read { /// `limit` is used to prevent a denial of service attack vector since an unbounded reader will /// exhaust all memory. /// - /// Similar to `std::io::Read::read_to_end` but with the DOS protection. + /// 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. #[doc(alias = "read_to_end")] #[cfg(feature = "alloc")] #[inline] @@ -83,6 +97,10 @@ pub trait Read { /// A trait describing an input stream that uses an internal buffer when reading. pub trait BufRead: Read { /// Returns data read from this reader, filling the internal buffer if needed. + /// + /// # Errors + /// + /// May error if reading fails. fn fill_buf(&mut self) -> Result<&[u8]>; /// Marks the buffered data up to amount as consumed. @@ -104,6 +122,12 @@ pub struct Take<'a, R: Read + ?Sized> { impl Take<'_, R> { /// Reads all bytes until EOF from the underlying reader into `buf`. + /// + /// Allocates space in `buf` as needed. + /// + /// # Returns + /// + /// The number of bytes read if successful or an [`Error`] if reading fails. #[cfg(feature = "alloc")] #[inline] pub fn read_to_end(&mut self, buf: &mut Vec) -> Result { @@ -274,7 +298,9 @@ impl> BufRead for Cursor { } } -/// A generic trait describing an output stream. See [`std::io::Write`] for more info. +/// A generic trait describing an output stream. +/// +/// See [`std::io::Write`] for more information. pub trait Write { /// Writes `buf` into this writer, returning how many bytes were written. fn write(&mut self, buf: &[u8]) -> Result; @@ -334,9 +360,9 @@ impl Write for &mut [u8] { fn flush(&mut self) -> Result<()> { Ok(()) } } -/// A sink to which all writes succeed. See [`std::io::Sink`] for more info. +/// A sink to which all writes succeed. /// -/// Created using `io::sink()`. +/// Created using [`sink()`]. See [`std::io::Sink`] for more information. #[derive(Clone, Copy, Debug, Default)] pub struct Sink; @@ -351,7 +377,9 @@ impl Write for Sink { fn flush(&mut self) -> Result<()> { Ok(()) } } -/// Returns a sink to which all writes succeed. See [`std::io::sink`] for more info. +/// Returns a sink to which all writes succeed. +/// +/// See [`std::io::sink`] for more information. #[inline] pub fn sink() -> Sink { Sink } From 9c81d5e74767b10c5a49bbdf9e3c38becbbd89b7 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Tue, 7 Jan 2025 10:46:09 +1100 Subject: [PATCH 4/5] io: Move macro_export below docs The `io::macros` crate uses a kind of nifty trick of putting `macro_export` _above_ the docs. But we do not do this anywhere else in the code base so its a bit surprising. We should be uniform. Simply because its an easier change move the `macro_export` attribute to be under the docs. Internal change only. --- io/src/macros.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/io/src/macros.rs b/io/src/macros.rs index 4904a826d..26e9d1a2d 100644 --- a/io/src/macros.rs +++ b/io/src/macros.rs @@ -1,6 +1,5 @@ // SPDX-License-Identifier: CC0-1.0 -#[macro_export] /// Because we cannot provide a blanket implementation of [`std::io::Write`] for all implementers /// of this crate's `io::Write` trait, we provide this macro instead. /// @@ -9,6 +8,7 @@ /// that feature. In any case, this crate's `io::Write` feature will be implemented for the given /// type, even if indirectly. #[cfg(not(feature = "std"))] +#[macro_export] macro_rules! impl_write { ($ty: ty, $write_fn: expr, $flush_fn: expr $(, $bounded_ty: ident : $bounds: path),*) => { impl<$($bounded_ty: $bounds),*> $crate::Write for $ty { @@ -24,7 +24,6 @@ macro_rules! impl_write { } } -#[macro_export] /// Because we cannot provide a blanket implementation of [`std::io::Write`] for all implementers /// of this crate's `io::Write` trait, we provide this macro instead. /// @@ -33,6 +32,7 @@ macro_rules! impl_write { /// that feature. In any case, this crate's `io::Write` feature will be implemented for the given /// type, even if indirectly. #[cfg(feature = "std")] +#[macro_export] macro_rules! impl_write { ($ty: ty, $write_fn: expr, $flush_fn: expr $(, $bounded_ty: ident : $bounds: path),*) => { impl<$($bounded_ty: $bounds),*> std::io::Write for $ty { From 71fab82a1b32e6077adb896be9d8ac12d5513e0a Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Tue, 7 Jan 2025 10:54:26 +1100 Subject: [PATCH 5/5] io: Improve docs on macro Note that the docsrs build enables all features so the `impl_write` macro gets a `std` feature flag even though it is available without the `std` feature enabled. I can't think of a solution to that slight annoyance ATM. The current docs on `impl_write` seem to be stale. The macro just does a simple call through implementation of `crate::Write` and the same for `std::io::Write` if `std` is enabled. Improve the rusdocs by doing: - Remove module level docs because this is a private module and they only add minimal value. - Put the docs on the `std` macro only (docs build uses --all-features) - Explain just what the macro does and include an `# Arguments` section. --- io/src/macros.rs | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/io/src/macros.rs b/io/src/macros.rs index 26e9d1a2d..55df18aa7 100644 --- a/io/src/macros.rs +++ b/io/src/macros.rs @@ -1,12 +1,7 @@ // SPDX-License-Identifier: CC0-1.0 -/// Because we cannot provide a blanket implementation of [`std::io::Write`] for all implementers -/// of this crate's `io::Write` trait, we provide this macro instead. -/// -/// This macro will implement `Write` given a `write` and `flush` fn, either by implementing the -/// crate's native `io::Write` trait directly, or a more generic trait from `std` for users using -/// that feature. In any case, this crate's `io::Write` feature will be implemented for the given -/// type, even if indirectly. +/// Implements [`crate::Write`] for `$ty`. +// See below for docs (docs.rs build enables all features). #[cfg(not(feature = "std"))] #[macro_export] macro_rules! impl_write { @@ -24,13 +19,16 @@ macro_rules! impl_write { } } -/// Because we cannot provide a blanket implementation of [`std::io::Write`] for all implementers -/// of this crate's `io::Write` trait, we provide this macro instead. +/// Implements [`crate::Write`] for `$ty`. /// -/// This macro will implement `Write` given a `write` and `flush` fn, either by implementing the -/// crate's native `io::Write` trait directly, or a more generic trait from `std` for users using -/// that feature. In any case, this crate's `io::Write` feature will be implemented for the given -/// type, even if indirectly. +/// Also implements [`std::io::Write`] for `$ty` if `bitcoin_io` has the `std` feature enabled. +/// +/// # Arguments +/// +/// * `$ty` - the type used to implement the two traits. +/// * `write_fn` - the function called by the `Write::write` trait method. +/// * `flush_fn` - the function called by the `Write::flush` trait method. +/// * `$bounded_ty: $bounds` - optional trait bounds if required. #[cfg(feature = "std")] #[macro_export] macro_rules! impl_write {