Improve documentation

crates/musli-core/src/context.rs

@@ -10,7 +10,7 @@ use crate::Allocator;
 ///
 /// This is used to among other things report diagnostics.
 pub trait Context: Copy {
-    /// Error produced by context.
+    /// Error produced by the context.
     type Error;
     /// A mark during processing.
     type Mark;
@@ -40,35 +40,35 @@ pub trait Context: Copy {
 
     /// Generate a map function which maps an error using the `custom` function.
     #[inline]
-    fn map<T>(self) -> impl FnOnce(T) -> Self::Error
+    fn map<E>(self) -> impl FnOnce(E) -> Self::Error
     where
-        T: 'static + Send + Sync + Error,
+        E: 'static + Send + Sync + Error,
     {
         move |error| self.custom(error)
     }
 
     /// Report a custom error, which is not encapsulated by the error type
     /// expected by the context. This is essentially a type-erased way of
     /// reporting error-like things out from the context.
-    fn custom<T>(self, error: T) -> Self::Error
+    fn custom<E>(self, error: E) -> Self::Error
     where
-        T: 'static + Send + Sync + Error;
+        E: 'static + Send + Sync + Error;
 
     /// Report a message as an error.
     ///
     /// This is made available to format custom error messages in `no_std`
     /// environments. The error message is to be collected by formatting `T`.
-    fn message<T>(self, message: T) -> Self::Error
+    fn message<M>(self, message: M) -> Self::Error
     where
-        T: fmt::Display;
+        M: fmt::Display;
 
     /// Report an error based on a mark.
     ///
     /// A mark is generated using [Context::mark] and indicates a prior state.
     #[inline]
-    fn marked_message<T>(self, mark: &Self::Mark, message: T) -> Self::Error
+    fn marked_message<M>(self, mark: &Self::Mark, message: M) -> Self::Error
     where
-        T: fmt::Display,
+        M: fmt::Display,
     {
         _ = mark;
         self.message(message)
@@ -78,9 +78,9 @@ pub trait Context: Copy {
     ///
     /// A mark is generated using [Context::mark] and indicates a prior state.
     #[inline]
-    fn marked_custom<T>(self, mark: &Self::Mark, message: T) -> Self::Error
+    fn marked_custom<E>(self, mark: &Self::Mark, message: E) -> Self::Error
     where
-        T: 'static + Send + Sync + Error,
+        E: 'static + Send + Sync + Error,
     {
         _ = mark;
         self.custom(message)
@@ -141,9 +141,9 @@ pub trait Context: Copy {
     ///
     /// [`leave_field`]: Context::leave_field
     #[inline]
-    fn enter_named_field<T>(self, type_name: &'static str, field: T)
+    fn enter_named_field<F>(self, type_name: &'static str, field: F)
     where
-        T: fmt::Display,
+        F: fmt::Display,
     {
         _ = type_name;
         _ = field;
@@ -169,9 +169,9 @@ pub trait Context: Copy {
     ///
     /// [`leave_field`]: Context::leave_field
     #[inline]
-    fn enter_unnamed_field<T>(self, index: u32, name: T)
+    fn enter_unnamed_field<F>(self, index: u32, name: F)
     where
-        T: fmt::Display,
+        F: fmt::Display,
     {
         _ = index;
         _ = name;
@@ -212,9 +212,9 @@ pub trait Context: Copy {
     ///
     /// [`leave_variant`]: Context::leave_variant
     #[inline]
-    fn enter_variant<T>(self, type_name: &'static str, tag: T)
+    fn enter_variant<V>(self, type_name: &'static str, tag: V)
     where
-        T: fmt::Display,
+        V: fmt::Display,
     {
         _ = type_name;
         _ = tag;
@@ -231,9 +231,9 @@ pub trait Context: Copy {
 
     /// Trace a that a map key has been entered.
     #[inline]
-    fn enter_map_key<T>(self, field: T)
+    fn enter_map_key<K>(self, field: K)
     where
-        T: fmt::Display,
+        K: fmt::Display,
     {
         _ = field;
     }

crates/musli/src/context/capture.rs

@@ -7,19 +7,19 @@ use super::{ContextError, ErrorMarker};
 
 mod sealed {
     pub trait Sealed {}
-    impl Sealed for super::NoCapture {}
-    impl<E, A> Sealed for super::CaptureError<E, A> {}
-    impl<E, A> Sealed for super::SameError<E, A> {}
+    impl Sealed for super::Ignore {}
+    impl<E> Sealed for super::Capture<E> {}
+    impl<E> Sealed for super::Emit<E> {}
 }
 
 /// The trait governing how error capture is implemented.
 ///
-/// See [`DefaultContext::with_capture`] or [`DefaultContext::with_same`] for
+/// See [`DefaultContext::with_capture`] or [`DefaultContext::with_error`] for
 /// more information.
 ///
 /// [`DefaultContext::with_capture`]: super::DefaultContext::with_capture
-/// [`DefaultContext::with_same`]: super::DefaultContext::with_same
-pub trait Capture<A>
+/// [`DefaultContext::with_error`]: super::DefaultContext::with_error
+pub trait ErrorMode<A>
 where
     Self: self::sealed::Sealed,
 {
@@ -41,10 +41,24 @@ where
 }
 
 /// Disable error capture.
+///
+/// The error produced will be an [`ErrorMarker`] which is a zero-sized
+/// placeholder type.
+///
+/// To capture an error, use [`with_capture::<E>`]. To produce an error see
+/// [`with_error::<E>`].
+///
+/// This is the default behavior you get when calling [`new`] or [`new_in`].
+///
+/// [`with_capture::<E>`]: super::DefaultContext::with_capture
+/// [`with_error::<E>`]: super::DefaultContext::with_error
+///
+/// [`new`]: super::new
+/// [`new_in`]: super::new_in
 #[non_exhaustive]
-pub struct NoCapture;
+pub struct Ignore;
 
-impl<A> Capture<A> for NoCapture {
+impl<A> ErrorMode<A> for Ignore {
     type Error = ErrorMarker;
 
     #[inline]
@@ -71,16 +85,16 @@ impl<A> Capture<A> for NoCapture {
     }
 }
 
-/// Capture an error of the specified type.
+/// Emit an error of the specified type `E`.
 ///
-/// See [`DefaultContext::with_same`] for more information.
+/// See [`DefaultContext::with_error`] for more information.
 ///
-/// [`DefaultContext::with_same`]: super::DefaultContext::with_same
-pub struct SameError<E, A> {
-    _marker: PhantomData<(E, A)>,
+/// [`DefaultContext::with_error`]: super::DefaultContext::with_error
+pub struct Emit<E> {
+    _marker: PhantomData<E>,
 }
 
-impl<E, A> SameError<E, A> {
+impl<E> Emit<E> {
     #[inline]
     pub(super) fn new() -> Self {
         Self {
@@ -89,7 +103,7 @@ impl<E, A> SameError<E, A> {
     }
 }
 
-impl<E, A> Capture<A> for SameError<E, A>
+impl<E, A> ErrorMode<A> for Emit<E>
 where
     E: ContextError<A>,
 {
@@ -115,27 +129,25 @@ where
     }
 }
 
-/// Capture an error of the specified type.
+/// Capture an error of the specified type `E`.
 ///
 /// See [`DefaultContext::with_capture`] for more information.
 ///
 /// [`DefaultContext::with_capture`]: super::DefaultContext::with_capture
-pub struct CaptureError<E, A> {
+pub struct Capture<E> {
     error: UnsafeCell<Option<E>>,
-    _marker: PhantomData<A>,
 }
 
-impl<E, A> CaptureError<E, A> {
+impl<E> Capture<E> {
     #[inline]
     pub(super) fn new() -> Self {
         Self {
             error: UnsafeCell::new(None),
-            _marker: PhantomData,
         }
     }
 }
 
-impl<E, A> CaptureError<E, A> {
+impl<E> Capture<E> {
     #[inline]
     pub(super) fn unwrap(&self) -> E {
         // SAFETY: We're restricting access to the context, so that this is
@@ -161,7 +173,7 @@ impl<E, A> CaptureError<E, A> {
     }
 }
 
-impl<E, A> Capture<A> for CaptureError<E, A>
+impl<E, A> ErrorMode<A> for Capture<E>
 where
     E: ContextError<A>,
 {