From f2533813ac4d92ff3733dc6c6041aa3a0c0b8b08 Mon Sep 17 00:00:00 2001
From: timofey <tim@ongoteam.yaconnect.com>
Date: Sun, 30 Jul 2023 10:45:21 +0000
Subject: [PATCH] `Mode` docs

---
 src/rcore/modes.rs | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/src/rcore/modes.rs b/src/rcore/modes.rs
index 9f7a6af..3a096d8 100644
--- a/src/rcore/modes.rs
+++ b/src/rcore/modes.rs
@@ -4,11 +4,24 @@ use super::*;
 
 pub type ModeResult<M, A, E, I> = Result<<M as Mode>::ParseSuccess<A, I>, E>;
 
+/// Mode of parsing.
 pub trait Mode {
+    /// Successful parsing, may countain the parser itself
+    /// (`I`, usually [`Inlining`]).
+    /// 
+    /// See [`FactoryParse::deserialize`].
     type ParseSuccess<A, I>;
 
+    /// Result of extending the value, failing sometimes or always.
+    ///
+    /// See [`FactoryParse::extend`].
     type ExtensionResult<A, E>;
 
+    /// Data enough to try extending the value.
+    /// 
+    /// May be empty for always-failing extensions.
+    ///
+    /// See [`FactoryParse::extend`].
     type ExtensionSource<A>;
 
     fn bind<A0, A1, E, I>(
@@ -21,6 +34,7 @@ pub trait Mode {
         f: impl FnOnce(A0) -> A1,
     ) -> Self::ParseSuccess<A1, I>;
 
+    /// Discard any extra information contained in [`Mode::ParseSuccess`].
     fn seal<A, I>(s: Self::ParseSuccess<A, I>) -> A;
 
     fn xmap_err<A, E0, E1>(
@@ -33,6 +47,7 @@ pub trait Mode {
         f: impl FnOnce(A0) -> Result<A1, E>,
     ) -> Self::ExtensionResult<A1, E>;
 
+    /// Convert [`Mode::ExtensionResult`] to [`Result`].
     fn xseal<A, E>(result: Self::ExtensionResult<A, E>) -> Result<A, E>;
 
     fn smap<A0, A1>(
@@ -42,6 +57,7 @@ pub trait Mode {
 
     fn prepare<A>(a: A) -> Self::ExtensionSource<A>;
 
+    /// For abstract [`FactoryParse::extend`] implementations.
     fn xsbind<AB, A, B, E>(
         ab: Self::ExtensionSource<AB>,
         t2ab: impl FnOnce(AB) -> (A, B),