Document more (#150)

README.md

@@ -240,7 +240,7 @@ struct Version2 {
 
 let version2 = musli::wire::to_vec(&Version2 {
     name: String::from("Aristotle"),
-    age: Some(62),
+    age: Some(61),
 })?;
 
 let version1: Version1 = musli::wire::decode(version2.as_slice())?;
@@ -255,7 +255,7 @@ versions.
 ```rust
 let version2 = musli::storage::to_vec(&Version2 {
     name: String::from("Aristotle"),
-    age: Some(62),
+    age: Some(61),
 })?;
 
 assert!(musli::storage::decode::<_, Version1>(version2.as_slice()).is_err());

crates/musli-core/src/context.rs

@@ -81,6 +81,7 @@ pub trait Context {
         T: ?Sized + fmt::Display;
 
     /// Generate a map function which maps an error using the `custom` function.
+    #[inline]
     fn map<T>(&self) -> impl FnOnce(T) -> Self::Error + '_
     where
         T: 'static + Send + Sync + no_std::Error,
@@ -96,6 +97,7 @@ pub trait Context {
         T: 'static + Send + Sync + no_std::Error;
 
     /// Generate a map function which maps an error using the `message` function.
+    #[inline]
     fn map_message<T>(&self) -> impl FnOnce(T) -> Self::Error + '_
     where
         T: fmt::Display,

crates/musli/README.md

@@ -240,7 +240,7 @@ struct Version2 {
 
 let version2 = musli::wire::to_vec(&Version2 {
     name: String::from("Aristotle"),
-    age: Some(62),
+    age: Some(61),
 })?;
 
 let version1: Version1 = musli::wire::decode(version2.as_slice())?;
@@ -255,7 +255,7 @@ versions.
 ```rust
 let version2 = musli::storage::to_vec(&Version2 {
     name: String::from("Aristotle"),
-    age: Some(62),
+    age: Some(61),
 })?;
 
 assert!(musli::storage::decode::<_, Version1>(version2.as_slice()).is_err());

crates/musli/src/allocator/mod.rs

@@ -13,7 +13,7 @@
 //! ```
 //! use musli::{Allocator, Buf};
 //!
-//! musli::default_allocator!(|alloc| {
+//! musli::allocator::default!(|alloc| {
 //!     let mut a = alloc.alloc().expect("allocation a failed");
 //!     let mut b = alloc.alloc().expect("allocation b failed");
 //!
@@ -58,10 +58,18 @@ mod stack;
 pub use self::stack::{Stack, StackBuffer};
 
 /// The default stack buffer size for the default allocator provided through
-/// [`default_allocator!`][crate::default_allocator].
+/// [`default!`].
 pub const DEFAULT_STACK_BUFFER: usize = 4096;
 
-/// Call the given block with the default allocator.
+#[macro_export]
+#[doc(hidden)]
+macro_rules! __default {
+    (|$alloc:ident| $body:block) => {
+        $crate::allocator::__default_allocator_impl!(|$alloc| $body)
+    };
+}
+
+/// Call the given block `$body` with the default allocator.
 ///
 /// This is useful if you want to write application which are agnostic to
 /// whether the `alloc` feature is or isn't enabled.
@@ -75,7 +83,7 @@ pub const DEFAULT_STACK_BUFFER: usize = 4096;
 /// ```
 /// use musli::{Allocator, Buf};
 ///
-/// musli::default_allocator!(|alloc| {
+/// musli::allocator::default!(|alloc| {
 ///     let mut a = alloc.alloc().expect("allocation a failed");
 ///     let mut b = alloc.alloc().expect("allocation b failed");
 ///
@@ -98,12 +106,8 @@ pub const DEFAULT_STACK_BUFFER: usize = 4096;
 ///     assert_eq!(a.len(), 12);
 /// });
 /// ```
-#[macro_export]
-macro_rules! default_allocator {
-    (|$alloc:ident| $body:block) => {
-        $crate::__default_allocator_impl!(|$alloc| $body)
-    };
-}
+#[doc(inline)]
+pub use __default as default;
 
 #[cfg(feature = "alloc")]
 #[macro_export]
@@ -126,3 +130,6 @@ macro_rules! __default_allocator_impl {
         $body
     }};
 }
+
+#[doc(hidden)]
+pub use __default_allocator_impl;

crates/musli/src/allocator/system.rs

@@ -8,7 +8,11 @@ use alloc::vec::Vec;
 use crate::buf::Error;
 use crate::{Allocator, Buf};
 
-/// Buffer used in combination with an [`Allocator`].
+/// System buffer that can be used in combination with an [`Allocator`].
+///
+/// This uses the [`System`] allocator.
+///
+/// [`System` allocator]: https://doc.rust-lang.org/std/alloc/struct.System.html
 pub struct System {
     internal: UnsafeCell<Internal>,
 }

crates/musli/src/descriptive/de.rs

@@ -649,7 +649,7 @@ where
     {
         let cx = self.cx;
 
-        let Some(tag) = self.reader.peek(cx)?.map(Tag::from_byte) else {
+        let Some(tag) = self.reader.peek().map(Tag::from_byte) else {
             return Err(cx.message("Expected tag in input"));
         };
 

crates/musli/src/descriptive/encoding.rs

@@ -1,18 +1,11 @@
 //! Module that defines [`Encoding`] whith allows for customization of the
 //! encoding format, and the [`DEFAULT`] encoding configuration.
 
-#[cfg(feature = "alloc")]
-use alloc::vec::Vec;
 use core::marker;
-#[cfg(feature = "std")]
-use std::io;
 
-use crate::de::Decode;
-use crate::en::Encode;
 use crate::mode::Binary;
 use crate::options;
-use crate::Context;
-use crate::{FixedBytes, Options, Reader, Writer};
+use crate::{IntoReader, Options};
 
 use super::de::SelfDecoder;
 use super::en::SelfEncoder;
@@ -32,69 +25,7 @@ pub const OPTIONS: options::Options = options::new().build();
 /// [`variable length`]: https://en.wikipedia.org/wiki/Variable-length_quantity
 pub const DEFAULT: Encoding = Encoding::new();
 
-/// Encode the given value to the given [`Writer`] using the [`DEFAULT`]
-/// configuration.
-#[inline]
-pub fn encode<W, T>(writer: W, value: &T) -> Result<(), Error>
-where
-    W: Writer,
-    T: ?Sized + Encode<Binary>,
-{
-    DEFAULT.encode(writer, value)
-}
-
-/// Encode the given value to the given [Write][io::Write] using the [`DEFAULT`]
-/// configuration.
-#[cfg(feature = "std")]
-#[inline]
-pub fn to_writer<W, T>(writer: W, value: &T) -> Result<(), Error>
-where
-    W: io::Write,
-    T: ?Sized + Encode<Binary>,
-{
-    DEFAULT.to_writer(writer, value)
-}
-
-/// Encode the given value to a [Vec] using the [`DEFAULT`] configuration.
-#[cfg(feature = "alloc")]
-#[inline]
-pub fn to_vec<T>(value: &T) -> Result<Vec<u8>, Error>
-where
-    T: ?Sized + Encode<Binary>,
-{
-    DEFAULT.to_vec(value)
-}
-
-/// Encode the given value to a fixed-size bytes using the [`DEFAULT`]
-/// configuration.
-#[inline]
-pub fn to_fixed_bytes<const N: usize, T>(value: &T) -> Result<FixedBytes<N>, Error>
-where
-    T: ?Sized + Encode<Binary>,
-{
-    DEFAULT.to_fixed_bytes::<N, _>(value)
-}
-
-/// Decode the given type `T` from the given [`Reader`] using the [`DEFAULT`]
-/// configuration.
-#[inline]
-pub fn decode<'de, R, T>(reader: R) -> Result<T, Error>
-where
-    R: Reader<'de>,
-    T: Decode<'de, Binary>,
-{
-    DEFAULT.decode(reader)
-}
-
-/// Decode the given type `T` from the given slice using the [`DEFAULT`]
-/// configuration.
-#[inline]
-pub fn from_slice<'de, T>(bytes: &'de [u8]) -> Result<T, Error>
-where
-    T: Decode<'de, Binary>,
-{
-    DEFAULT.from_slice(bytes)
-}
+crate::macros::bare_encoding!(Binary, DEFAULT, descriptive, IntoReader);
 
 /// Setting up encoding with parameters.
 pub struct Encoding<const OPT: Options = OPTIONS, M = Binary> {
@@ -112,21 +43,21 @@ impl Encoding<OPTIONS, Binary> {
     /// Construct a new [`Encoding`] instance.
     ///
     /// ```
-    /// use musli::descriptive::{Encoding};
     /// use musli::{Encode, Decode};
+    /// use musli::descriptive::Encoding;
+    /// # use musli::descriptive::Error;
     ///
     /// const CONFIG: Encoding = Encoding::new();
     ///
     /// #[derive(Debug, PartialEq, Encode, Decode)]
-    /// struct Struct<'a> {
+    /// struct Person<'a> {
     ///     name: &'a str,
     ///     age: u32,
     /// }
     ///
-    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
     /// let mut out = Vec::new();
     ///
-    /// let expected = Struct {
+    /// let expected = Person {
     ///     name: "Aristotle",
     ///     age: 61,
     /// };
@@ -135,7 +66,7 @@ impl Encoding<OPTIONS, Binary> {
     /// let actual = CONFIG.decode(&out[..])?;
     ///
     /// assert_eq!(expected, actual);
-    /// # Ok(()) }
+    /// # Ok::<_, Error>(())
     /// ```
     pub const fn new() -> Self {
         Encoding {
@@ -179,11 +110,12 @@ impl<const OPT: Options, M> Encoding<OPT, M> {
         }
     }
 
-    crate::encoding_impls!(
+    crate::macros::encoding_impls!(
         M,
         descriptive,
         SelfEncoder::<_, OPT, _>::new,
-        SelfDecoder::<_, OPT, _>::new
+        SelfDecoder::<_, OPT, _>::new,
+        IntoReader::into_reader,
     );
 }
 

crates/musli/src/descriptive/mod.rs

@@ -35,7 +35,7 @@
 //!
 //! let version2 = musli::descriptive::to_vec(&Version2 {
 //!     name: String::from("Aristotle"),
-//!     age: Some(62),
+//!     age: Some(61),
 //! })?;
 //!
 //! let version1: Version1 = musli::descriptive::decode(version2.as_slice())?;
@@ -60,14 +60,14 @@
 //! const CONFIG: Encoding = Encoding::new();
 //!
 //! #[derive(Debug, PartialEq, Encode, Decode)]
-//! struct Struct<'a> {
+//! struct Person<'a> {
 //!     name: &'a str,
 //!     age: u32,
 //! }
 //!
 //! let mut out = Vec::new();
 //!
-//! let expected = Struct {
+//! let expected = Person {
 //!     name: "Aristotle",
 //!     age: 61,
 //! };

crates/musli/src/descriptive/test.rs

@@ -1,3 +1,3 @@
 //! Helpers for writing tests.
 
-crate::test_fns!("descriptive", crate::mode::Binary, #[musli_value]);
+crate::macros::test_fns!(Binary, "descriptive", #[musli_value]);

crates/musli/src/help/derives.rs

@@ -43,8 +43,8 @@
 //! const TEXT: Encoding = Encoding::new();
 //! const BINARY: Encoding<Binary> = Encoding::new().with_mode();
 //!
-//! let named = TEXT.to_vec(&Person { not_name: "Aristotle", age: 62 })?;
-//! assert_eq!(named.as_slice(), br#"{"name":"Aristotle","age":62}"#);
+//! let named = TEXT.to_vec(&Person { not_name: "Aristotle", age: 61 })?;
+//! assert_eq!(named.as_slice(), br#"{"name":"Aristotle","age":61}"#);
 //!
 //! let indexed = BINARY.to_vec(&Person { not_name: "Plato", age: 84 })?;
 //! assert_eq!(indexed.as_slice(), br#"{"0":"Plato","1":84}"#);

crates/musli/src/int/encoding.rs

@@ -100,6 +100,7 @@ where
         crate::options::Integer::Variable => c::encode(cx, writer, value),
         _ => {
             let bo = crate::options::byteorder::<OPT>();
+
             macro_rules! fixed {
                 ($ty:ty) => {{
                     let Ok(value) = <$ty>::try_from(value) else {
@@ -110,7 +111,7 @@ where
                 }};
             }
 
-            crate::width_arm!(crate::options::length_width::<OPT>(), fixed)
+            crate::options::width_arm!(crate::options::length_width::<OPT>(), fixed)
         }
     }
 }
@@ -139,7 +140,7 @@ where
                 }};
             }
 
-            crate::width_arm!(crate::options::length_width::<OPT>(), fixed)
+            crate::options::width_arm!(crate::options::length_width::<OPT>(), fixed)
         }
     }
 }

crates/musli/src/int/tests.rs

@@ -16,7 +16,7 @@ const ITER: usize = 100;
 
 #[test]
 fn basic_continuation() {
-    crate::default_allocator!(|alloc| {
+    crate::allocator::default!(|alloc| {
         let cx = context::Ignore::marker(&alloc);
         let mut bytes = FixedBytes::<8>::new();
         c::encode(&cx, &mut bytes, 5000u32).unwrap();
@@ -36,7 +36,7 @@ fn test_continuation_encoding() {
     where
         T: PartialEq<T> + fmt::Debug + Unsigned,
     {
-        crate::default_allocator!(|alloc| {
+        crate::allocator::default!(|alloc| {
             let mut out = Vec::new();
             let cx = crate::context::Ignore::marker(&alloc);
             c::encode(&cx, &mut out, expected).unwrap();
@@ -55,7 +55,7 @@ fn test_continuation_encoding() {
     where
         T: Unsigned,
     {
-        crate::default_allocator!(|alloc| {
+        crate::allocator::default!(|alloc| {
             let mut out = Vec::new();
             let cx = crate::context::Same::marker(&alloc);
             c::encode(&cx, crate::wrap::wrap(&mut out), value).unwrap();

crates/musli/src/json/de/key_decoder.rs

@@ -169,7 +169,7 @@ where
     where
         V: Visitor<'de, C>,
     {
-        match self.parser.peek(self.cx)? {
+        match self.parser.lex(self.cx) {
             Token::String => {
                 let visitor = visitor.visit_string(self.cx, SizeHint::any())?;
                 self.decode_string(visitor)