From 71fab82a1b32e6077adb896be9d8ac12d5513e0a Mon Sep 17 00:00:00 2001
From: "Tobin C. Harding" <me@tobin.cc>
Date: Tue, 7 Jan 2025 10:54:26 +1100
Subject: [PATCH] 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 {