io: Remove the impl_write macro

We want to release a stable version of the `io` crate. As such we are
trying to minimise the API that we commit to. The `impl_write` macro is
by design meant to be called by other crates and experience has shown us
that doing so is error prone. The code produced by the macro is pretty
basic to write and it is likely write-once-read-many code.

Deprecate the macro. While we are at it point users to the examples in
`bitcoin/examples/io.rs` for usage of the `io` crate.

io/src/lib.rs

@@ -7,6 +7,9 @@
 //!
 //! These traits are not one-for-one drop-ins, but are as close as possible while still implementing
 //! `std::io`'s traits without unnecessary complexity.
+//!
+//! For examples of how to use and implement the types and traits in this crate see `io.rs` in the
+//! `github.com/rust-bitcoin/rust-bitcoin/bitcoin/examples/` directory.
 
 #![cfg_attr(not(feature = "std"), no_std)]
 // Experimental features we need.

io/src/macros.rs

@@ -9,6 +9,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"))]
+#[deprecated(since = "TBD", note = "this macro was deemed unnecessary for upcoming 1.0 release")]
 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 {
@@ -33,6 +34,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")]
+#[deprecated(since = "TBD", note = "this macro was deemed unnecessary for upcoming 1.0 release")]
 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 {