From 1858a7fb862af23832c229725522042f0cb8b895 Mon Sep 17 00:00:00 2001
From: John-John Tedro <udoprog@tedro.se>
Date: Wed, 13 Mar 2024 16:59:15 +0100
Subject: [PATCH] Clean up documentation

---
 crates/musli-allocator/Cargo.toml   |  4 +-
 crates/musli-allocator/src/lib.rs   | 93 ++++++++++++-----------------
 crates/musli-allocator/src/stack.rs |  4 +-
 3 files changed, 42 insertions(+), 59 deletions(-)

diff --git a/crates/musli-allocator/Cargo.toml b/crates/musli-allocator/Cargo.toml
index 94b054391..7c137bf3f 100644
--- a/crates/musli-allocator/Cargo.toml
+++ b/crates/musli-allocator/Cargo.toml
@@ -13,8 +13,8 @@ categories = ["no-std", "memory-management", "rust-patterns"]
 
 [features]
 default = ["std"]
-std = ["alloc"]
-alloc = []
+std = ["alloc", "musli/std"]
+alloc = ["musli/alloc"]
 
 [dependencies]
 musli = { path = "../musli", version = "0.0.96", default-features = false }
diff --git a/crates/musli-allocator/src/lib.rs b/crates/musli-allocator/src/lib.rs
index c050da61f..023658a47 100644
--- a/crates/musli-allocator/src/lib.rs
+++ b/crates/musli-allocator/src/lib.rs
@@ -36,95 +36,78 @@ mod disabled;
 pub use self::disabled::Disabled;
 
 pub mod stack;
+#[doc(inline)]
 pub use self::stack::{Stack, StackBuffer};
 
 mod fixed;
 #[doc(hidden)]
 pub use self::fixed::{FixedString, FixedVec};
 
+/// The default stack buffer size.
+pub const DEFAULT_STACK_BUFFER: usize = 4096;
+
 #[cfg(feature = "alloc")]
 mod default_alloc {
-    #![allow(missing_docs)]
-
-    use musli::Allocator;
-
-    pub struct DefaultBuffer(super::SystemBuffer);
-    pub struct Default<'a>(super::System<'a>);
+    #[doc(hidden)]
+    pub type DefaultBuffer = super::SystemBuffer;
+    #[doc(hidden)]
+    pub type Default<'a> = super::System<'a>;
 
     pub(super) fn buffer() -> DefaultBuffer {
-        DefaultBuffer(super::SystemBuffer::new())
+        DefaultBuffer::new()
     }
 
-    pub(super) fn new(DefaultBuffer(buf): &mut DefaultBuffer) -> Default<'_> {
-        Default(super::System::new(buf))
-    }
-
-    impl<'a> Allocator for Default<'a> {
-        type Buf<'this> = <super::System<'a> as Allocator>::Buf<'this>
-        where
-            Self: 'this;
-
-        #[inline(always)]
-        fn alloc(&self) -> Option<Self::Buf<'_>> {
-            self.0.alloc()
-        }
+    pub(super) fn new(buf: &mut DefaultBuffer) -> Default<'_> {
+        Default::new(buf)
     }
 }
 
 #[cfg(not(feature = "alloc"))]
 mod default_alloc {
-    #![allow(missing_docs)]
+    use super::DEFAULT_STACK_BUFFER;
 
-    use musli::Allocator;
-
-    type InnerAllocator<'a> = super::Stack<'a>;
-
-    pub struct DefaultBuffer(super::StackBuffer<4096>);
-    pub struct Default<'a>(InnerAllocator<'a>);
+    #[doc(hidden)]
+    pub type DefaultBuffer = super::StackBuffer<{ DEFAULT_STACK_BUFFER }>;
+    #[doc(hidden)]
+    pub type Default<'a> = super::Stack<'a>;
 
     pub(super) fn buffer() -> DefaultBuffer {
-        DefaultBuffer(super::StackBuffer::new())
+        DefaultBuffer::new()
     }
 
-    pub(super) fn new(DefaultBuffer(buf): &mut DefaultBuffer) -> Default<'_> {
-        Default(super::Stack::new(buf))
+    pub(super) fn new(buf: &mut DefaultBuffer) -> Default<'_> {
+        Default::new(buf)
     }
+}
 
-    impl<'a> Allocator for Default<'a> {
-        type Buf<'this> = <super::Stack<'a> as super::Allocator>::Buf<'this>
-        where
-            Self: 'this;
+/// The default backing allocator buffer.
+///
+/// * If the `alloc` feature is enabled, this is [`SystemBuffer`].
+/// * Otherwise this is [`StackBuffer`] with a default size of
+///   [`DEFAULT_STACK_BUFFER`].
+#[doc(inline)]
+pub use self::default_alloc::DefaultBuffer;
 
-        #[inline(always)]
-        fn alloc(&self) -> Option<Self::Buf<'_>> {
-            self.0.alloc()
-        }
-    }
-}
+/// The default allocator.
+///
+/// * If the `alloc` feature is enabled, this is the [`System`] allocator.
+/// * Otherwise this is the [`Stack`] allocator.
+#[doc(inline)]
+pub use self::default_alloc::Default;
 
 /// Construct a new default buffer.
 ///
-/// Uses [`HeapBuffer`] if the `alloc` feature is enabled, otherwise
-/// `StackBuffer` is used with a default size of `4096`.
+/// * If the `alloc` feature is enabled, this is [`SystemBuffer`].
+/// * Otherwise this is [`StackBuffer`] with a default size of
+///   [`DEFAULT_STACK_BUFFER`].
 pub fn buffer() -> DefaultBuffer {
     self::default_alloc::buffer()
 }
 
 /// Construct a new default allocator.
 ///
-/// Uses the [`Alloc`] allocator if the `alloc` feature is enabled, otherwise
-/// [`Stack`].
-///
-/// Requires that [`buffer()`] is used to construct the provided buffer.
+/// * If the `alloc` feature is enabled, this is the [`System`] allocator.
+/// * Otherwise this is the [`Stack`] allocator.
 pub fn new(buf: &mut DefaultBuffer) -> Default<'_> {
     self::default_alloc::new(buf)
 }
-
-/// The default allocator.
-///
-/// The exact implementation depends on which features are enabled (first one
-/// takes preference):
-/// * If `alloc` is enabled, this is the [`Alloc`] allocator.
-/// * Otherwise this is the [`Stack`] allocator.
-#[doc(inline)]
-pub use self::default_alloc::{Default, DefaultBuffer};
diff --git a/crates/musli-allocator/src/stack.rs b/crates/musli-allocator/src/stack.rs
index 2f9f9ad13..03fa75f4a 100644
--- a/crates/musli-allocator/src/stack.rs
+++ b/crates/musli-allocator/src/stack.rs
@@ -74,7 +74,7 @@ use core::slice;
 
 use musli::{Allocator, Buf};
 
-use crate::FixedVec;
+use crate::{FixedVec, DEFAULT_STACK_BUFFER};
 
 const HEADER_U32: u32 = size_of::<Header>() as u32;
 // We keep max bytes to 2^31, since that ensures that addition between two
@@ -84,7 +84,7 @@ const MAX_BYTES: u32 = i32::MAX as u32;
 /// A buffer that can be used to store data on the stack.
 ///
 /// See the [module level documentation][self] for more information.
-pub struct StackBuffer<const C: usize> {
+pub struct StackBuffer<const C: usize = DEFAULT_STACK_BUFFER> {
     data: FixedVec<u8, C>,
 }