Expose the formatting macros. (yewstack#883)

This allows users to create their own encoding wrappers.

The provided documentation uses real-life examples from within yew.
This commit also fixes a minor oversight, where use of the
text_format_is_an_error macro required the end-user to explicitly use
the text_format macro instead of simply bringing it in itself.

Cargo.toml

@@ -51,6 +51,8 @@ ryu = "1.0.2" # 1.0.1 breaks emscripten
 serde_derive = "1"
 trybuild = "1.0"
 rustversion = "1.0"
+rmp-serde = "0.14.0"
+bincode = "~1.2.1"
 
 [features]
 default = ["services", "agent"]

src/format/macros.rs

@@ -1,5 +1,23 @@
-//! Contains macro for wrapping serde format.
+//! Contains three macros for wrapping serde format.  Collectively they
+//! allow you to define your own text and binary wrappers.
 
+#[macro_export]
+/// This macro is used for a format that can be encoded as Text.  It
+/// is used in conjunction with a type definition for a tuple struct
+/// with one (publically accessible) element of a generic type.  Since
+/// any type that can be encoded as Text can also be encoded as Binary,
+/// it should be used with the binary_format macro.
+///
+/// ## Example
+///
+/// ```rust
+/// use yew::{binary_format, text_format};
+///
+/// pub struct Json<T>(pub T);
+///
+/// text_format!(Json based on serde_json);
+/// binary_format!(Json based on serde_json);
+/// ```
 macro_rules! text_format {
     ($type:ident based on $format:ident) => {
         impl<'a, T> Into<$crate::format::Text> for $type<&'a T>
@@ -25,6 +43,66 @@ macro_rules! text_format {
     };
 }
 
+#[macro_export]
+/// This macro is used for a format that can be encoded as Binary.  It
+/// is used in conjunction with a type definition for a tuple struct
+/// with one (publicly accessible) element of a generic type.  Not
+/// all types that can be encoded as Binary can be encoded as Text.
+/// As such, this macro should be paired with the text_format macro
+/// where such an encoding works (e.g., JSON), or with the
+/// text_format_is_an_error macro for binary-only formats (e.g.,
+/// MsgPack).
+///
+/// # Rely on serde's `to_vec` and `from_vec`
+/// The simplest form of this macro relegates all the work to serde's
+/// `to_vec` function for serialization and serde's `from_vec` for
+/// deseriaization.
+///
+/// ## Examples
+///
+/// ### Binary that is also Text
+///
+/// ```rust
+/// use yew::{binary_format, text_format};
+///
+/// pub struct Json<T>(pub T);
+///
+/// text_format!(Json based on serde_json);
+/// binary_format!(Json based on serde_json);
+/// ```
+///
+/// ### Binary only
+/// ```rust
+/// # mod to_make_rustdoc_happy {
+///   use rmp_serde;
+///   use yew::{binary_format, text_format_is_an_error};
+///
+///   pub struct MsgPack<T>(pub T);
+///
+///   binary_format!(MsgPack based on rmp_serde);
+///   text_format_is_an_error!(MsgPack);
+/// # }
+/// ```
+///
+/// # Supply serialization and deserialization functions
+///
+/// In addition to the "based on" form of this macro demonstrated above,
+/// you can use the three parameter second form to supply
+/// non-standard (i.e., alternatives to serde's `to_vec` and/or `from_slice`)
+/// helpers as the second and third parameters.
+///
+/// ## Example
+/// ```rust
+/// # mod to_make_rustdoc_happy {
+///   use bincode;
+///   use yew::{binary_format, text_format_is_an_error};
+///
+///   pub struct Bincode<T>(pub T);
+///
+///   binary_format!(Bincode, bincode::serialize, bincode::deserialize);
+///   text_format_is_an_error!(Bincode);
+/// # }
+/// ```
 macro_rules! binary_format {
     ($type:ident based on $format:ident) => {
         binary_format!($type, $format::to_vec, $format::from_slice);
@@ -53,9 +131,29 @@ macro_rules! binary_format {
     };
 }
 
+#[macro_export]
+/// This macro is used for a format that can be encoded as Binary but
+/// can't be encoded as Text.  It is used in conjunction with a type
+/// definition for a tuple struct with one (publically accessible)
+/// element of a generic type.  This macro should be paired with the
+/// binary_format macro that defines the binary-only format.
+///
+/// ## Example
+/// ```rust
+/// # mod to_make_rustdoc_happy {
+///   use rmp_serde;
+///   use yew::{binary_format, text_format_is_an_error};
+///
+///   pub struct MsgPack<T>(pub T);
+///
+///   binary_format!(MsgPack based on rmp_serde);
+///   text_format_is_an_error!(MsgPack);
+/// # }
+/// ```
+
 macro_rules! text_format_is_an_error {
     ($type:ident) => {
-        use $crate::format::FormatError;
+        use $crate::{format::FormatError, text_format};
 
         fn to_string<T>(_value: T) -> Result<String, ::anyhow::Error> {
             Err(FormatError::CantEncodeBinaryAsText.into())