Merge rust-bitcoin/rust-bitcoin#3874: io: Improve the docs

71fab82a1b io: Improve docs on macro (Tobin C. Harding)
9c81d5e747 io: Move macro_export below docs (Tobin C. Harding)
b109177e11 io: Improve rustdocs (Tobin C. Harding)
07d8703a00 io: Add SPDX identifier (Tobin C. Harding)
b844637935 io: Remove rustdoc for private module (Tobin C. Harding)

Pull request description:

  As part of #3643 improve the public documentation on the `io` crate.

  While doing this I also checked:

  - C-FAILURE
  - C-LINK
  -  C-METADATA
  - C-RELNOTES
  - C-HIDDEN

ACKs for top commit:
  apoelstra:
    ACK 71fab82a1b32e6077adb896be9d8ac12d5513e0a; successfully ran local tests

Tree-SHA512: 91b8807102277fb7f6602837b7d0e64e4276c9c5bf748ab875ea0e4f1f7f91bc989413acd25e4412d72d6f3744a22b746ed63cbac20d9b42217cd3164c7e6847

io/src/bridge.rs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: CC0-1.0
+
 #[cfg(feature = "alloc")]
 use alloc::boxed::Box;
 

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;

io/src/lib.rs

@@ -1,8 +1,10 @@
+// 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
+//! 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
@@ -41,12 +43,22 @@ pub use self::error::{Error, ErrorKind};
 /// Result type returned by functions in this crate.
 pub type Result<T> = core::result::Result<T, Error>;
 
-/// 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<usize>;
 
     /// 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() {
@@ -69,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]
@@ -81,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.
@@ -102,6 +122,12 @@ pub struct Take<'a, R: Read + ?Sized> {
 
 impl<R: Read + ?Sized> 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<u8>) -> Result<usize> {
@@ -272,7 +298,9 @@ impl<T: AsRef<[u8]>> BufRead for Cursor<T> {
     }
 }
 
-/// 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<usize>;
@@ -332,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;
 
@@ -349,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 }
 

io/src/macros.rs

@@ -1,14 +1,9 @@
-//! Public macros for porvide.d for users to be able implement our `io::Write` trait.
+// 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.
-///
-/// 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 {
     ($ty: ty, $write_fn: expr, $flush_fn: expr $(, $bounded_ty: ident : $bounds: path),*) => {
         impl<$($bounded_ty: $bounds),*> $crate::Write for $ty {
@@ -24,15 +19,18 @@ 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.
+/// 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 {
     ($ty: ty, $write_fn: expr, $flush_fn: expr $(, $bounded_ty: ident : $bounds: path),*) => {
         impl<$($bounded_ty: $bounds),*> std::io::Write for $ty {