nom 8 missing docs (#1703)

* mark internal types as private

they are not really useful to construct manually

* single and double precision float parsers

the f64 parser was implemented during the GAT migration, but not the f32
one

* 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>,

src/number/mod.rs

@@ -29,6 +29,10 @@ pub enum Endianness {
   Native,
 }
 
+/// creates a big endian unsigned integer parser
+///
+/// * `bound`: the number of bytes that will be read
+/// * `Uint`: the output type
 #[inline]
 fn be_uint<I, Uint, E: ParseError<I>>(bound: usize) -> impl Parser<I, Output = Uint, Error = E>
 where
@@ -42,8 +46,8 @@ where
   }
 }
 
-/// todo
-pub struct BeUint<Uint, E> {
+/// Big endian unsigned integer parser
+struct BeUint<Uint, E> {
   bound: usize,
   e: PhantomData<E>,
   u: PhantomData<Uint>,
@@ -341,6 +345,10 @@ where
   be_u128().map(|x| x as i128)
 }
 
+/// creates a little endian unsigned integer parser
+///
+/// * `bound`: the number of bytes that will be read
+/// * `Uint`: the output type
 #[inline]
 fn le_uint<I, Uint, E: ParseError<I>>(bound: usize) -> impl Parser<I, Output = Uint, Error = E>
 where
@@ -354,8 +362,8 @@ where
   }
 }
 
-/// todo
-pub struct LeUint<Uint, E> {
+/// Little endian unsigned integer parser
+struct LeUint<Uint, E> {
   bound: usize,
   e: PhantomData<E>,
   u: PhantomData<Uint>,
@@ -1314,7 +1322,7 @@ where
   ))
 }
 
-///todo
+/// float number text parser that also recognizes "nan", "infinity" and "inf" (case insensitive)
 pub fn recognize_float_or_exceptions<T, E: ParseError<T>>() -> impl Parser<T, Output = T, Error = E>
 where
   T: Clone + Offset,
@@ -1338,7 +1346,22 @@ where
   ))
 }
 
-/// TODO
+/// single precision floating point number parser from text
+pub fn float<T, E: ParseError<T>>() -> impl Parser<T, Output = f32, Error = E>
+where
+  T: Clone + Offset,
+  T: Input + crate::traits::ParseTo<f32> + Compare<&'static str>,
+  <T as Input>::Item: AsChar + Clone,
+  T: AsBytes,
+  T: for<'a> Compare<&'a [u8]>,
+{
+  Float {
+    o: PhantomData,
+    e: PhantomData,
+  }
+}
+
+/// double precision floating point number parser from text
 pub fn double<T, E: ParseError<T>>() -> impl Parser<T, Output = f64, Error = E>
 where
   T: Clone + Offset,
@@ -1347,23 +1370,27 @@ where
   T: AsBytes,
   T: for<'a> Compare<&'a [u8]>,
 {
-  Double { e: PhantomData }
+  Float {
+    o: PhantomData,
+    e: PhantomData,
+  }
 }
 
-/// TODO
-pub struct Double<E> {
+/// f64 parser from text
+struct Float<O, E> {
+  o: PhantomData<O>,
   e: PhantomData<E>,
 }
 
-impl<I, E: ParseError<I>> Parser<I> for Double<E>
+impl<I, O, E: ParseError<I>> Parser<I> for Float<O, E>
 where
   I: Clone + Offset,
-  I: Input + crate::traits::ParseTo<f64> + Compare<&'static str>,
+  I: Input + crate::traits::ParseTo<O> + Compare<&'static str>,
   <I as Input>::Item: AsChar + Clone,
   I: AsBytes,
   I: for<'a> Compare<&'a [u8]>,
 {
-  type Output = f64;
+  type Output = O;
   type Error = E;
 
   fn process<OM: crate::OutputMode>(