future-proof: remove write! from the public API

book/src/SUMMARY.md

@@ -10,7 +10,7 @@
     - [Bitfields](./bitfields.md)
     - [Interned strings](./istr.md)
   - [#[derive(Format)]](./format.md)
-  - [write!](./write.md)
+  <!-- - [write!](./write.md) -->
   - [Filtering](./filtering.md)
   - [#[timestamp]](./timestamp.md)
   - [#[global_logger]](./global-logger.md)

book/src/format.md

@@ -1,6 +1,6 @@
 # `#[derive(Format)]`
 
-The preferred way to implement the `Format` trait for a struct or enum is to use the `derive` attribute.
+To implement the `Format` trait for a struct or enum use the `derive` attribute.
 
 ``` rust
 #[derive(Format)]

macros/src/lib.rs

@@ -241,7 +241,7 @@ pub fn format(ts: TokenStream) -> TokenStream {
         Data::Struct(ds) => {
             fs = ident.to_string();
             let args = fields(&ds.fields, &mut fs, Kind::Struct);
-            exprs.push(quote!(binfmt::write!(f, #fs #(,#args)*);))
+            exprs.push(quote!(binfmt::export::write!(f, #fs #(,#args)*);))
         }
 
         Data::Union(..) => {

src/export.rs

@@ -1,5 +1,6 @@
 use crate::{Formatter, Str};
 
+pub use binfmt_macros::write;
 pub use common::Level;
 
 #[cfg(target_arch = "x86_64")]

src/lib.rs

@@ -97,26 +97,6 @@ pub use binfmt_macros::global_logger;
 /// ```
 pub use binfmt_macros::timestamp;
 
-/// Writes binfmt-formatted data to a [`Formatter`].
-///
-/// This works similarly to the `write!` macro in libcore.
-///
-/// Usage:
-///
-/// ```
-/// # use binfmt::{Format, Formatter};
-/// # struct S;
-/// # impl Format for S {
-/// #     fn format(&self, formatter: &mut Formatter) {
-/// #         let arguments = 0u8;
-/// binfmt::write!(formatter, "format string {:?}", arguments)
-/// #     }
-/// # }
-/// ```
-///
-/// [`Formatter`]: struct.Formatter.html
-pub use binfmt_macros::write;
-
 #[doc(hidden)]
 pub use binfmt_macros::winfo;
 #[doc(hidden)] // documented as the `Format` trait instead
@@ -395,7 +375,7 @@ pub trait Write {
 ///
 /// # Example
 ///
-/// It is recommended to `#[derive]` implementations of this trait:
+/// It is required to `#[derive]` implementations of this trait:
 ///
 /// ```
 /// use binfmt::Format;
@@ -407,30 +387,6 @@ pub trait Write {
 ///     sequence: u16,
 /// }
 /// ```
-///
-/// If necessary, implementations can also be written manually:
-///
-/// ```
-/// use binfmt::{Format, Formatter};
-///
-/// struct Header {
-///     source: u8,
-///     destination: u8,
-///     sequence: u16,
-/// }
-///
-/// impl Format for Header {
-///     fn format(&self, fmt: &mut Formatter) {
-///         binfmt::write!(
-///             fmt,
-///             "Header {{ source: {:u8}, destination: {:u8}, sequence: {:u16} }}",
-///             self.source,
-///             self.destination,
-///             self.sequence
-///         )
-///     }
-/// }
-/// ```
 pub trait Format {
     /// Writes the binfmt representation of `self` to `fmt`.
     fn format(&self, fmt: &mut Formatter);

src/tests.rs

@@ -36,7 +36,7 @@ fn trailing_comma() {
     #[allow(unreachable_code, unused_variables)]
     if false {
         let fmt: binfmt::Formatter = panic!();
-        binfmt::write!(fmt, "test write",);
-        binfmt::write!(fmt, "test write {:?}", 0,);
+        binfmt::export::write!(fmt, "test write",);
+        binfmt::export::write!(fmt, "test write {:?}", 0,);
     }
 }