nom 8 missing docs (rust-bakery#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>(