A few doc improvments to /docs and others

doc/choosing_a_combinator.md

@@ -26,7 +26,7 @@ Those are used to recognize the lowest level elements of your grammar, like, "he
 
 | combinator | usage | input | output | comment |
 |---|---|---|---|---|
-| [alt](https://docs.rs/nom/latest/nom/branch/fn.alt.html) | `alt((tag("ab"), tag("cd")))` |  `"cdef"` | `Ok(("ef", "cd"))` |Try a list of parsers and return the result of the first successful one|
+| [alt](https://docs.rs/nom/latest/nom/branch/fn.alt.html) | `alt((tag("ab"), tag("cd")))` |  `"cdef"` | `Ok(("ef", "cd"))` |Try a list of parsers and return the result of the first successful one. All child parsers have the same `Output`.|
 | [permutation](https://docs.rs/nom/latest/nom/branch/fn.permutation.html) | `permutation((tag("ab"), tag("cd"), tag("12")))` | `"cd12abc"` | `Ok(("c", ("ab", "cd", "12"))` |Succeeds when all its child parser have succeeded, whatever the order|
 
 ## Sequence combinators
@@ -38,7 +38,7 @@ Those are used to recognize the lowest level elements of your grammar, like, "he
 | [terminated](https://docs.rs/nom/latest/nom/sequence/fn.terminated.html) | `terminated(tag("ab"), tag("XY"))` | `"abXYZ"` | `Ok(("Z", "ab"))` |Gets an object from the first parser, then matches an object from the second parser and discards it.|
 | [pair](https://docs.rs/nom/latest/nom/sequence/fn.pair.html) | `pair(tag("ab"), tag("XY"))` | `"abXYZ"` | `Ok(("Z", ("ab", "XY")))` |Gets an object from the first parser, then gets another object from the second parser.|
 | [separated_pair](https://docs.rs/nom/latest/nom/sequence/fn.separated_pair.html) | `separated_pair(tag("hello"), char(','), tag("world"))` | `"hello,world!"` | `Ok(("!", ("hello", "world")))` |Gets an object from the first parser, then matches an object from the sep_parser and discards it, then gets another object from the second parser.|
-| [tuple](https://docs.rs/nom/latest/nom/sequence/fn.tuple.html) | `tuple((tag("ab"), tag("XY"), take(1)))` | `"abXYZ!"` | `Ok(("!", ("ab", "XY", "Z")))` | Chains parsers and assemble the sub results in a tuple. You can use as many child parsers as you can put elements in a tuple|
+| tuples | `((tag("ab"), tag("XY"), take(1)))` | `"abXYZ!"` | `Ok(("!", ("ab", "XY", "Z")))` | `Parser` is implemented for tuples: it chains parsers and assemble the sub results in a tuple. You can use as many child parsers as you can put elements in a tuple|
 
 ## Applying a parser multiple times
 
@@ -106,7 +106,7 @@ The following parsers could be found on [docs.rs number section](https://docs.rs
 
 - [`escaped`](https://docs.rs/nom/latest/nom/bytes/complete/fn.escaped.html): Matches a byte string with escaped characters
 - [`escaped_transform`](https://docs.rs/nom/latest/nom/bytes/complete/fn.escaped_transform.html): Matches a byte string with escaped characters, and returns a new string with the escaped characters replaced
-- [`precedence`](https://docs.rs/nom/latest/nom/precedence/fn.precedence.html): Parses an expression with regards to operator precedence
+- [`precedence`](https://docs.rs/nom-language/latest/nom_language/precedence/fn.precedence.html) (from `nom-language`): Parses an expression with regards to operator precedence
 
 ## Binary format parsing
 

doc/custom_input_types.md

@@ -1,3 +1,5 @@
+> **Note:** This document is for `nom7`. These traits were replaced in `nom8` by one `Input` trait, with the same principles.
+
 # Custom input types
 
 While historically, nom has worked mainly on `&[u8]` and `&str`, it can actually

doc/error_management.md

@@ -115,9 +115,9 @@ println!(
 );
 ```
 
-### getting more information: nom::error::VerboseError
+### getting more information: nom-language::error::VerboseError
 
-The  `VerboseError<I>` type accumulates more information about the chain of
+The  `VerboseError<I>` type (available from the companion `nom-language` crate) accumulates more information about the chain of
 parsers that encountered an error:
 
 ```rust
@@ -187,7 +187,7 @@ println!("parsed verbose: {:#?}", json::<VerboseError<&str>>(data));
 ```
 
 But by looking at the original input and the chain of errors, we can build
-a more user friendly error message. The `nom::error::convert_error` function
+a more user friendly error message. The `nom-language::error::convert_error` function
 can build such a message.
 
 ```rust
@@ -232,7 +232,7 @@ information, like line and column.
 
 #### nom-supreme
 
-[nom-supreme](https://docs.rs/nom-supreme) provides the `ErrorTree<I>` error
+[nom-supreme](https://docs.rs/nom-supreme) (not updated yet for `nom8`) provides the `ErrorTree<I>` error
 type, that provides the same chain of parser errors as `VerboseError`, but also
 accumulates errors from the various branches tried by `alt`.
 

doc/making_a_new_parser_from_scratch.md

@@ -54,7 +54,7 @@ use nom::bytes::complete::take;
 
 pub fn length_value(input: &[u8]) -> IResult<&[u8],&[u8]> {
     let (input, length) = be_u16(input)?;
-    take(length)(input)
+    take(length).parse_complete(input)
 }
 ```
 
@@ -194,7 +194,7 @@ prints its hexdump if the child parser encountered an error:
 use nom::{IResult, error::dbg_dmp, bytes::complete::tag};
 
 fn f(i: &[u8]) -> IResult<&[u8], &[u8]> {
-  dbg_dmp(tag("abcd"), "tag")(i)
+  dbg_dmp(tag("abcd"), "tag").parse(i)
 }
 
   let a = &b"efghijkl"[..];

doc/nom_recipes.md

@@ -365,8 +365,8 @@ use std::str::FromStr;
 // will recognize the name in "Hello, name!"
 fn parse_name(input: &str) -> IResult<&str, &str> {
   let (i, _) = tag("Hello, ").parse(input)?;
-  let (i, name) = take_while(|c:char| c.is_alphabetic())(i)?;
-  let (i, _) = tag("!")(i)?;
+  let (i, name) = take_while(|c:char| c.is_alphabetic()).parse(i)?;
+  let (i, _) = tag("!").parse(i)?;
 
   Ok((i, name))
 }

src/branch/mod.rs

@@ -14,6 +14,8 @@ use crate::internal::{Err, Mode, Parser};
 /// It takes as argument either a tuple or an array of parsers. If using a
 /// tuple, there is a maximum of 21 parsers. If you need more, it is possible to
 /// use an array.
+/// 
+/// Errors if all parsers do not output the same type.
 ///
 /// ```rust
 /// # use nom::error_position;

src/internal.rs

@@ -408,13 +408,18 @@ pub trait Parser<Input> {
 
   /// A parser takes in input type, and returns a `Result` containing
   /// either the remaining input and the output value, or an error
+  /// 
+  /// Use this function for streaming parsers that recognize incomplete input.
   #[inline]
   fn parse(&mut self, input: Input) -> IResult<Input, Self::Output, Self::Error> {
     self.process::<OutputM<Emit, Emit, Streaming>>(input)
   }
 
   /// A parser takes in input type, and returns a `Result` containing
   /// either the remaining input and the output value, or an error
+  /// 
+  /// Use this function for complete parsers that fail on incomplete 
+  /// input. This should be used in `nom7` style function parsers.
   #[inline]
   fn parse_complete(&mut self, input: Input) -> IResult<Input, Self::Output, Self::Error> {
     self.process::<OutputM<Emit, Emit, Complete>>(input)

src/sequence/mod.rs

@@ -72,7 +72,7 @@ where
   }
 }
 
-/// a
+/// Parser wrapper for `preceded`
 pub struct Preceded<F, G> {
   f: F,
   g: G,
@@ -129,7 +129,7 @@ where
   }
 }
 
-/// a
+/// Parser wrapper for `terminated` 
 pub struct Terminated<F, G> {
   f: F,
   g: G,