more docs

src/character/mod.rs

@@ -388,7 +388,7 @@ where
   Digit1 { e: PhantomData }
 }
 
-/// todo
+/// Parser implementation for [digit1]
 pub struct Digit1<E> {
   e: PhantomData<E>,
 }
@@ -435,7 +435,7 @@ where
   })*/
 }
 
-/// TODO
+/// Parser implementation for [multispace0()]
 pub struct MultiSpace0<E> {
   e: PhantomData<E>,
 }

src/internal.rs

@@ -239,25 +239,33 @@ where
   }
 }
 
-/// TODO
+/// Parser mode: influences how combinators build values
+///
+/// the [Parser] trait is generic over types implementing [Mode]. Its method are
+/// called to produce and manipulate output values or errors.
+///
+/// The main implementations of this trait are:
+/// * [Emit]: produce a value
+/// * [Check]: apply the parser but do not generate a value
 pub trait Mode {
-  /// TODO
+  /// The output type that may be generated
   type Output<T>;
 
-  /// TODO
+  /// Produces a value
   fn bind<T, F: FnOnce() -> T>(f: F) -> Self::Output<T>;
-  /// TODO
+
+  /// Applies a function over the produced value
   fn map<T, U, F: FnOnce(T) -> U>(x: Self::Output<T>, f: F) -> Self::Output<U>;
 
-  /// TODO
+  /// Combines two values generated by previous parsers
   fn combine<T, U, V, F: FnOnce(T, U) -> V>(
     x: Self::Output<T>,
     y: Self::Output<U>,
     f: F,
   ) -> Self::Output<V>;
 }
 
-/// TODO
+/// Produces a value. This is the default behaviour for parsers
 pub struct Emit;
 impl Mode for Emit {
   type Output<T> = T;
@@ -282,7 +290,12 @@ impl Mode for Emit {
   }
 }
 
-/// TODO
+/// Applies the parser, but do not a produce a value
+///
+/// This has the effect of greatly reducing the amount of code generated and the
+/// parser memory usage. Some combinators chek for an error in a child parser but
+/// discard the error, and for those, using [Check] makes sure the error is not
+/// even generated, only the fact that an error happened remains
 pub struct Check;
 impl Mode for Check {
   type Output<T> = ();
@@ -302,31 +315,52 @@ impl Mode for Check {
   }
 }
 
-/// TODO
+/// Parser result type
+///
+/// * `Ok` branch: a tuple of the remaining input data, and the output value.
+/// The output value is of the `O` type if the output mode was [Emit], and `()`
+/// if the mode was [Check]
+/// * `Err` branch: an error of the `E` type if the erroor mode was [Emit], and `()`
+/// if the mode was [Check]
 pub type PResult<OM, I, O, E> = Result<
   (I, <<OM as OutputMode>::Output as Mode>::Output<O>),
   Err<E, <<OM as OutputMode>::Error as Mode>::Output<E>>,
 >;
 
-/// TODO
+/// Trait Defining the parser's execution
+///
+/// The same parser implementation can vary in behaviour according to the chosen
+/// output mode
 pub trait OutputMode {
-  /// TODO
+  /// Defines the [Mode] for the output type. [Emit] will generate the value, [Check] will
+  /// apply the parser but will only generate `()` if successul. This can be used when
+  /// verifying that the input data conforms to the format without having to generate any
+  /// output data
   type Output: Mode;
-  /// TODO
+  /// Defines the [Mode] for the output type. [Emit] will generate the value, [Check] will
+  /// apply the parser but will only generate `()` if an error happened. [Emit] should be
+  /// used when we want to handle the error and extract useful information from it. [Check]
+  /// is used when we just want to know if parsing failed and reject the data quickly.
   type Error: Mode;
-  /// TODO
+  /// Indicates whether the input data is "complete", ie we already have the entire data in the
+  /// buffer, or if it is "streaming", where more data can be added later in the buffer. In
+  /// streaming mode, the parser will understand that a failure may mean that we are missing
+  /// data, and will return a specific error branch, [Err::Incomplete] to signal it. In complete
+  /// mode, the parser will generate a normal error
   type Incomplete: IsStreaming;
 }
 
-/// TODO
+/// Specifies the behaviour when a parser encounters an error that could be due to partial ata
 pub trait IsStreaming {
-  /// TODO
+  /// called by parsers on partial data errors
+  /// * `needed` can hold the amount of dditional data the parser would need to decide
+  /// * `err_f`: produces the error when in "complete" mode
   fn incomplete<E, F: FnOnce() -> E>(needed: Needed, err_f: F) -> Err<E>;
-  /// TODO
+  /// Indicates whether the data is in streaming mode or not
   fn is_streaming() -> bool;
 }
 
-/// TODO
+/// Indicates that the input data is streaming: more data may be available later
 pub struct Streaming;
 
 impl IsStreaming for Streaming {
@@ -340,7 +374,7 @@ impl IsStreaming for Streaming {
   }
 }
 
-/// TODO
+/// Indicates that the input data is complete: no more data may be added later
 pub struct Complete;
 
 impl IsStreaming for Complete {
@@ -354,7 +388,8 @@ impl IsStreaming for Complete {
   }
 }
 
-/// a
+/// Holds the parser execution modifiers: output [Mode], error [Mode] and
+/// streaming behaviour for input data
 pub struct OutputM<M: Mode, EM: Mode, S: IsStreaming> {
   m: PhantomData<M>,
   em: PhantomData<EM>,