Repository: Geal/nom
Pull request #938 (2019-05-03 03:29:17)

[5.0] Add doc for sequence/mod.rs
Add documentation for sequence/mod.rs
It is related with #915 .


Patch:
diff --git a/src/branch/macros.rs b/src/branch/macros.rs
index 69cfa7e..e64c99f 100644
--- a/src/branch/macros.rs
+++ b/src/branch/macros.rs
@@ -441,7 +441,7 @@ macro_rules! switch (
     {
       use $crate::lib::std::result::Result::*;
       use $crate::lib::std::option::Option::*;
-      use $crate::{Err,Convert,error::ErrorKind};
+      use $crate::{Err,error::ErrorKind};
 
       let i_ = $i.clone();
       match map!(i_, $submac!($($args)*), Some) {
@@ -565,7 +565,7 @@ macro_rules! permutation (
     {
       use $crate::lib::std::result::Result::*;
       use $crate::lib::std::option::Option::*;
-      use $crate::{Err,Convert,error::ErrorKind};
+      use $crate::{Err,error::ErrorKind};
 
       let mut res    = permutation_init!((), $($rest)*);
       let mut input  = $i;
diff --git a/src/branch/mod.rs b/src/branch/mod.rs
index 2a9a06f..354baef 100644
--- a/src/branch/mod.rs
+++ b/src/branch/mod.rs
@@ -7,8 +7,11 @@ use error::ErrorKind;
 use error::ParseError;
 use internal::{Err, IResult};
 
-/// helper trait for arguments to [alt]
+/// helper trait for the [alt] combinator
+///
+/// this trait is implemented for tuples of up to 21 elements
 pub trait Alt<I, O, E> {
+  /// tests each parser in the tuple and returns the result of the first one that succeeds
   fn choice(&self, input: I) -> IResult<I, O, E>;
 }
 
@@ -43,8 +46,11 @@ pub fn alt<I: Clone, O, E: ParseError<I>, List: Alt<I, O, E>>(l: List) -> impl F
   move |i: I| l.choice(i)
 }
 
-/// helper trait for arguments to [permutation]
+/// helper trait for the [permutation] combinator
+///
+/// this trait is implemented for tuples of up to 21 elements
 pub trait Permutation<I, O, E> {
+  /// tries to apply all parsers in the tuple in various orders until all of them succeed
   fn permutation(&self, input: I) -> IResult<I, O, E>;
 }
 
diff --git a/src/bytes/complete.rs b/src/bytes/complete.rs
index 8573b46..6ef4fec 100644
--- a/src/bytes/complete.rs
+++ b/src/bytes/complete.rs
@@ -7,6 +7,26 @@ use lib::std::ops::RangeFrom;
 use lib::std::result::Result::*;
 use traits::{Compare, CompareResult, FindSubstring, FindToken, InputIter, InputLength, InputTake, InputTakeAtPosition, Slice, ToUsize};
 
+/// Recognizes a pattern
+///
+/// The input data will be compared to the tag combinator's argument and will return the part of
+/// the input that matches the argument
+///
+/// It will return `Err(Err::Error((_, ErrorKind::Tag)))` if the input doesn't match the pattern
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::complete::tag;
+///
+/// fn parser(s: &str) -> IResult<&str, &str> {
+///   tag("Hello")(s)
+/// }
+///
+/// assert_eq!(parser("Hello, World!"), Ok((", World!", "Hello")));
+/// assert_eq!(parser("Something"), Err(Err::Error(("Something", ErrorKind::Tag))));
+/// assert_eq!(parser(""), Err(Err::Error(("", ErrorKind::Tag))));
+/// ```
 pub fn tag<'a, T: 'a, Input: 'a, Error: ParseError<Input>>(tag: T) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTake + Compare<T>,
@@ -26,6 +46,28 @@ where
   }
 }
 
+/// Recognizes a case insensitive pattern
+///
+/// The input data will be compared to the tag combinator's argument and will return the part of
+/// the input that matches the argument with no regard to case
+///
+/// It will return `Err(Err::Error((_, ErrorKind::Tag)))` if the input doesn't match the pattern
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::complete::tag_no_case;
+///
+/// fn parser(s: &str) -> IResult<&str, &str> {
+///   tag_no_case("hello")(s)
+/// }
+///
+/// assert_eq!(parser("Hello, World!"), Ok((", World!", "Hello")));
+/// assert_eq!(parser("hello, World!"), Ok((", World!", "hello")));
+/// assert_eq!(parser("HeLlO, World!"), Ok((", World!", "HeLlO")));
+/// assert_eq!(parser("Something"), Err(Err::Error(("Something", ErrorKind::Tag))));
+/// assert_eq!(parser(""), Err(Err::Error(("", ErrorKind::Tag))));
+/// ```
 pub fn tag_no_case<T, Input, Error: ParseError<Input>>(tag: T) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTake + Compare<T>,
@@ -46,6 +88,28 @@ where
   }
 }
 
+/// Parse till certain characters are met
+///
+/// The parser will return the longest slice till one of the characters of the combinator's argument are met.
+///
+/// It doesn't consume the matched character,
+///
+/// It will return a `Err::Error(("", ErrorKind::IsNot))` if the pattern wasn't met
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::complete::is_not;
+///
+/// fn not_space(s: &str) -> IResult<&str, &str> {
+///   is_not(" \t\r\n")(s)
+/// }
+///
+/// assert_eq!(not_space("Hello, World!"), Ok((" World!", "Hello,")));
+/// assert_eq!(not_space("Sometimes\t"), Ok(("\t", "Sometimes")));
+/// assert_eq!(not_space("Nospace"), Ok(("", "Nospace")));
+/// assert_eq!(not_space(""), Err(Err::Error(("", ErrorKind::IsNot))));
+/// ```
 pub fn is_not<T, Input, Error: ParseError<Input>>(arr: T) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTakeAtPosition,
@@ -57,6 +121,29 @@ where
   }
 }
 
+/// Returns the longest slice of the matches the pattern
+///
+/// The parser will return the longest slice consisting of the characters in provided in the
+/// combinator's argument
+///
+/// It will return a `Err(Err::Error((_, ErrorKind::IsA)))` if the pattern wasn't met
+///
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::complete::is_a;
+///
+/// fn hex(s: &str) -> IResult<&str, &str> {
+///   is_a("1234567890ABCDEF")(s)
+/// }
+///
+/// assert_eq!(hex("123 and voila"), Ok((" and voila", "123")));
+/// assert_eq!(hex("DEADBEEF and others"), Ok((" and others", "DEADBEEF")));
+/// assert_eq!(hex("BADBABEsomething"), Ok(("something", "BADBABE")));
+/// assert_eq!(hex("D15EA5E"), Ok(("", "D15EA5E")));
+/// assert_eq!(hex(""), Err(Err::Error(("", ErrorKind::IsA))));
+/// ```
 pub fn is_a<T, Input, Error: ParseError<Input>>(arr: T) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTakeAtPosition,
@@ -68,6 +155,27 @@ where
   }
 }
 
+/// Returns the longest input slice (if any) that matches the predicate
+///
+/// The parser will return the longest slice that matches the given predicate *(a function that
+/// takes the input and returns a bool)*
+///
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::complete::take_while;
+/// use nom::character::is_alphabetic;
+///
+/// fn alpha(s: &[u8]) -> IResult<&[u8], &[u8]> {
+///   take_while(is_alphabetic)(s)
+/// }
+///
+/// assert_eq!(alpha(b"latin123"), Ok((&b"123"[..], &b"latin"[..])));
+/// assert_eq!(alpha(b"12345"), Ok((&b"12345"[..], &b""[..])));
+/// assert_eq!(alpha(b"latin"), Ok((&b""[..], &b"latin"[..])));
+/// assert_eq!(alpha(b""), Ok((&b""[..], &b""[..])));
+/// ```
 pub fn take_while<F, Input, Error: ParseError<Input>>(cond: F) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTakeAtPosition,
@@ -76,6 +184,28 @@ where
   move |i: Input| i.split_at_position_complete(|c| !cond(c))
 }
 
+/// Returns the longest (atleast 1) input slice that matches the predicate
+///
+/// The parser will return the longest slice that matches the given predicate *(a function that
+/// takes the input and returns a bool)*
+///
+/// It will return an `Err(Err::Error((_, ErrorKind::TakeWhile1)))` if the pattern wasn't met
+///
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::complete::take_while1;
+/// use nom::character::is_alphabetic;
+///
+/// fn alpha(s: &[u8]) -> IResult<&[u8], &[u8]> {
+///   take_while1(is_alphabetic)(s)
+/// }
+///
+/// assert_eq!(alpha(b"latin123"), Ok((&b"123"[..], &b"latin"[..])));
+/// assert_eq!(alpha(b"latin"), Ok((&b""[..], &b"latin"[..])));
+/// assert_eq!(alpha(b"12345"), Err(Err::Error((&b"12345"[..], ErrorKind::TakeWhile1))));
+/// ```
 pub fn take_while1<F, Input, Error: ParseError<Input>>(cond: F) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTakeAtPosition,
@@ -87,6 +217,31 @@ where
   }
 }
 
+/// Returns the longest (m <= len <= n) input slice  that matches the predicate
+///
+/// The parser will return the longest slice that matches the given predicate *(a function that
+/// takes the input and returns a bool)*
+///
+/// It will return an `Err::Error((_, ErrorKind::TakeWhileMN))` if the pattern wasn't met or is out
+/// of range (m <= len <= n)
+///
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::complete::take_while_m_n;
+/// use nom::character::is_alphabetic;
+///
+/// fn short_alpha(s: &[u8]) -> IResult<&[u8], &[u8]> {
+///   take_while_m_n(3, 6, is_alphabetic)(s)
+/// }
+///
+/// assert_eq!(short_alpha(b"latin123"), Ok((&b"123"[..], &b"latin"[..])));
+/// assert_eq!(short_alpha(b"lengthy"), Ok((&b"y"[..], &b"length"[..])));
+/// assert_eq!(short_alpha(b"latin"), Ok((&b""[..], &b"latin"[..])));
+/// assert_eq!(short_alpha(b"ed"), Err(Err::Error((&b"ed"[..], ErrorKind::TakeWhileMN))));
+/// assert_eq!(short_alpha(b"12345"), Err(Err::Error((&b"12345"[..], ErrorKind::TakeWhileMN))));
+/// ```
 pub fn take_while_m_n<F, Input, Error: ParseError<Input>>(m: usize, n: usize, cond: F) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTake + InputIter + InputLength + Slice<RangeFrom<usize>>,
@@ -137,6 +292,26 @@ where
   }
 }
 
+/// Returns the longest input slice (if any) till a predicate is met
+///
+/// The parser will return the longest slice till the given predicate *(a function that
+/// takes the input and returns a bool)*
+///
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::complete::take_till;
+///
+/// fn till_colon(s: &str) -> IResult<&str, &str> {
+///   take_till(|c| c == ':')(s)
+/// }
+///
+/// assert_eq!(till_colon("latin:123"), Ok((":123", "latin")));
+/// assert_eq!(till_colon(":empty matched"), Ok((":empty matched", ""))); //allowed
+/// assert_eq!(till_colon("12345"), Ok(("", "12345")));
+/// assert_eq!(till_colon(""), Ok(("", "")));
+/// ```
 pub fn take_till<F, Input, Error: ParseError<Input>>(cond: F) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTakeAtPosition,
@@ -145,6 +320,29 @@ where
   move |i: Input| i.split_at_position_complete(|c| cond(c))
 }
 
+/// Returns the longest (atleast 1) input slice till a predicate is met
+///
+/// The parser will return the longest slice till the given predicate *(a function that
+/// takes the input and returns a bool)*
+///
+/// It will return `Err(Err::Error((_, ErrorKind::TakeTill1)))` if the input is empty or the
+/// predicate matches the first input
+///
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::complete::take_till1;
+///
+/// fn till_colon(s: &str) -> IResult<&str, &str> {
+///   take_till1(|c| c == ':')(s)
+/// }
+///
+/// assert_eq!(till_colon("latin:123"), Ok((":123", "latin")));
+/// assert_eq!(till_colon(":empty matched"), Err(Err::Error((":empty matched", ErrorKind::TakeTill1))));
+/// assert_eq!(till_colon("12345"), Ok(("", "12345")));
+/// assert_eq!(till_colon(""), Err(Err::Error(("", ErrorKind::TakeTill1))));
+/// ```
 pub fn take_till1<F, Input, Error: ParseError<Input>>(cond: F) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTakeAtPosition,
@@ -156,6 +354,25 @@ where
   }
 }
 
+/// Returns an input slice containing the first N input elements (Input[..N])
+/// 
+/// It will return `Err(Err::Error((_, ErrorKind::Eof)))` if the input is shorter than the argument
+///
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::complete::take;
+///
+/// fn take6(s: &str) -> IResult<&str, &str> {
+///   take(6usize)(s)
+/// }
+///
+/// assert_eq!(take6("1234567"), Ok(("7", "123456")));
+/// assert_eq!(take6("things"), Ok(("", "things")));
+/// assert_eq!(take6("short"), Err(Err::Error(("short", ErrorKind::Eof))));
+/// assert_eq!(take6(""), Err(Err::Error(("", ErrorKind::Eof))));
+/// ```
 pub fn take<C, Input, Error: ParseError<Input>>(count: C) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputIter + InputTake,
@@ -168,6 +385,25 @@ where
   }
 }
 
+/// Returns the longest input slice till it matches the pattern.
+///
+/// It doesn't consume the pattern. It will return `Err(Err::Error((_, ErrorKind::TakeUntil)))`
+/// if the pattern wasn't met
+///
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::complete::take_until;
+///
+/// fn until_eof(s: &str) -> IResult<&str, &str> {
+///   take_until("eof")(s)
+/// }
+///
+/// assert_eq!(until_eof("hello, worldeof"), Ok(("eof", "hello, world")));
+/// assert_eq!(until_eof("hello, world"), Err(Err::Error(("hello, world", ErrorKind::TakeUntil))));
+/// assert_eq!(until_eof(""), Err(Err::Error(("", ErrorKind::TakeUntil))));
+/// ```
 pub fn take_until<T, Input, Error: ParseError<Input>>(tag: T) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTake + FindSubstring<T>,
@@ -183,6 +419,28 @@ where
   }
 }
 
+/// Matches a byte string with escaped characters.
+///
+/// * The first argument matches the normal characters (it must not accept the control character),
+/// * the second argument is the control character (like `\` in most languages),
+/// * the third argument matches the escaped characters
+///
+/// # Example
+/// ```
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// # use nom::character::complete::digit1;
+/// use nom::bytes::complete::escaped;
+/// use nom::character::complete::one_of;
+///
+/// fn esc(s: &str) -> IResult<&str, &str> {
+///   escaped(digit1, '\\', one_of("\"n\\"))(s)
+/// }
+///
+/// assert_eq!(esc("123;"), Ok((";", "123")));
+/// assert_eq!(esc("12\\\"34;"), Ok((";", "12\\\"34")));
+/// ```
+///
 pub fn escaped<Input, Error, F, G, O1, O2>(normal: F, control_char: char, escapable: G) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: Clone + ::traits::Offset + InputLength + InputTake + InputTakeAtPosition + Slice<RangeFrom<usize>> + InputIter,
@@ -250,6 +508,16 @@ where
   escaped(normal, control_char, escapable)(i)
 }
 
+/// Matches a byte string with escaped characters.
+///
+/// * The first argument matches the normal characters (it must not match the control character),
+/// * the second argument is the control character (like `\` in most languages),
+/// * the third argument matches the escaped characters and transforms them.
+///
+/// As an example, the chain `abc\tdef` could be `abc    def` (it also consumes the control character)
+///
+/// # Example
+/// Currently Unavailable
 pub fn escaped_transform<Input, Error, F, G, O1, O2, ExtendItem, Output>(
   normal: F,
   control_char: char,
@@ -341,4 +609,4 @@ where
 {
   escaped_transform(normal, control_char, transform)(i)
 
-}
\ No newline at end of file
+}
diff --git a/src/bytes/streaming.rs b/src/bytes/streaming.rs
index d3fbc13..4c2c1c8 100644
--- a/src/bytes/streaming.rs
+++ b/src/bytes/streaming.rs
@@ -7,6 +7,24 @@ use lib::std::ops::RangeFrom;
 use lib::std::result::Result::*;
 use traits::{Compare, CompareResult, FindSubstring, FindToken, InputIter, InputLength, InputTake, InputTakeAtPosition, Slice, ToUsize};
 
+/// Recognizes a pattern
+///
+/// The input data will be compared to the tag combinator's argument and will return the part of
+/// the input that matches the argument
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::streaming::tag;
+///
+/// fn parser(s: &str) -> IResult<&str, &str> {
+///   tag("Hello")(s)
+/// }
+///
+/// assert_eq!(parser("Hello, World!"), Ok((", World!", "Hello")));
+/// assert_eq!(parser("Something"), Err(Err::Error(("Something", ErrorKind::Tag))));
+/// assert_eq!(parser(""), Err(Err::Incomplete(Needed::Size(5))));
+/// ```
 pub fn tag<'a, T: 'a, Input: 'a, Error: ParseError<Input>>(tag: T) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTake + Compare<T>,
@@ -28,6 +46,26 @@ where
   }
 }
 
+/// Recognizes a case insensitive pattern
+///
+/// The input data will be compared to the tag combinator's argument and will return the part of
+/// the input that matches the argument with no regard to case
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::streaming::tag_no_case;
+///
+/// fn parser(s: &str) -> IResult<&str, &str> {
+///   tag_no_case("hello")(s)
+/// }
+///
+/// assert_eq!(parser("Hello, World!"), Ok((", World!", "Hello")));
+/// assert_eq!(parser("hello, World!"), Ok((", World!", "hello")));
+/// assert_eq!(parser("HeLlO, World!"), Ok((", World!", "HeLlO")));
+/// assert_eq!(parser("Something"), Err(Err::Error(("Something", ErrorKind::Tag))));
+/// assert_eq!(parser(""), Err(Err::Incomplete(Needed::Size(5))));
+/// ```
 pub fn tag_no_case<T, Input, Error: ParseError<Input>>(tag: T) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTake + Compare<T>,
@@ -49,6 +87,28 @@ where
   }
 }
 
+/// Parse till certain characters are met
+///
+/// The parser will return the longest slice till one of the characters of the combinator's argument are met.
+///
+/// It doesn't consume the matched character,
+///
+/// It will return a `Err::Incomplete(Needed::Size(1))` if the pattern wasn't met
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::streaming::is_not;
+///
+/// fn not_space(s: &str) -> IResult<&str, &str> {
+///   is_not(" \t\r\n")(s)
+/// }
+///
+/// assert_eq!(not_space("Hello, World!"), Ok((" World!", "Hello,")));
+/// assert_eq!(not_space("Sometimes\t"), Ok(("\t", "Sometimes")));
+/// assert_eq!(not_space("Nospace"), Err(Err::Incomplete(Needed::Size(1))));
+/// assert_eq!(not_space(""), Err(Err::Incomplete(Needed::Size(1))));
+/// ```
 pub fn is_not<T, Input, Error: ParseError<Input>>(arr: T) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTakeAtPosition,
@@ -60,6 +120,30 @@ where
   }
 }
 
+/// Returns the longest slice of the matches the pattern
+///
+/// The parser will return the longest slice consisting of the characters in provided in the
+/// combinator's argument
+///
+/// # Streaming specific
+/// *Streaming version* will return a `Err::Incomplete(Needed::Size(1))` if the pattern wasn't met
+/// or if the pattern reaches the end of the input
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::streaming::is_a;
+///
+/// fn hex(s: &str) -> IResult<&str, &str> {
+///   is_a("1234567890ABCDEF")(s)
+/// }
+///
+/// assert_eq!(hex("123 and voila"), Ok((" and voila", "123")));
+/// assert_eq!(hex("DEADBEEF and others"), Ok((" and others", "DEADBEEF")));
+/// assert_eq!(hex("BADBABEsomething"), Ok(("something", "BADBABE")));
+/// assert_eq!(hex("D15EA5E"), Err(Err::Incomplete(Needed::Size(1))));
+/// assert_eq!(hex(""), Err(Err::Incomplete(Needed::Size(1))));
+/// ```
 pub fn is_a<T, Input, Error: ParseError<Input>>(arr: T) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTakeAtPosition,
@@ -71,6 +155,29 @@ where
   }
 }
 
+/// Returns the longest input slice (if any) that matches the predicate
+///
+/// The parser will return the longest slice that matches the given predicate *(a function that
+/// takes the input and returns a bool)*
+///
+/// # Streaming Specific
+/// *Streaming version* will return a `Err::Incomplete(Needed::Size(1))` if the pattern reaches the end of the input
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::streaming::take_while;
+/// use nom::character::is_alphabetic;
+///
+/// fn alpha(s: &[u8]) -> IResult<&[u8], &[u8]> {
+///   take_while(is_alphabetic)(s)
+/// }
+///
+/// assert_eq!(alpha(b"latin123"), Ok((&b"123"[..], &b"latin"[..])));
+/// assert_eq!(alpha(b"12345"), Ok((&b"12345"[..], &b""[..])));
+/// assert_eq!(alpha(b"latin"), Err(Err::Incomplete(Needed::Size(1))));
+/// assert_eq!(alpha(b""), Err(Err::Incomplete(Needed::Size(1))));
+/// ```
 pub fn take_while<F, Input, Error: ParseError<Input>>(cond: F) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTakeAtPosition,
@@ -79,6 +186,31 @@ where
   move |i: Input| i.split_at_position(|c| !cond(c))
 }
 
+/// Returns the longest (atleast 1) input slice that matches the predicate
+///
+/// The parser will return the longest slice that matches the given predicate *(a function that
+/// takes the input and returns a bool)*
+///
+/// It will return an `Err(Err::Error((_, ErrorKind::TakeWhile1)))` if the pattern wasn't met
+///
+/// # Streaming Specific
+/// *Streaming version* will return a `Err::Incomplete(Needed::Size(1))` or if the pattern reaches the end of the input.
+///
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::streaming::take_while1;
+/// use nom::character::is_alphabetic;
+///
+/// fn alpha(s: &[u8]) -> IResult<&[u8], &[u8]> {
+///   take_while1(is_alphabetic)(s)
+/// }
+///
+/// assert_eq!(alpha(b"latin123"), Ok((&b"123"[..], &b"latin"[..])));
+/// assert_eq!(alpha(b"latin"), Err(Err::Incomplete(Needed::Size(1))));
+/// assert_eq!(alpha(b"12345"), Err(Err::Error((&b"12345"[..], ErrorKind::TakeWhile1))));
+/// ```
 pub fn take_while1<F, Input, Error: ParseError<Input>>(cond: F) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTakeAtPosition,
@@ -90,6 +222,32 @@ where
   }
 }
 
+/// Returns the longest (m <= len <= n) input slice  that matches the predicate
+///
+/// The parser will return the longest slice that matches the given predicate *(a function that
+/// takes the input and returns a bool)*
+///
+/// It will return an `Err::Error((_, ErrorKind::TakeWhileMN))` if the pattern wasn't met
+/// # Streaming Specific
+/// *Streaming version* will return a `Err::Incomplete(Needed::Size(1))`  if the pattern reaches the end of the input or is too short.
+///
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::streaming::take_while_m_n;
+/// use nom::character::is_alphabetic;
+///
+/// fn short_alpha(s: &[u8]) -> IResult<&[u8], &[u8]> {
+///   take_while_m_n(3, 6, is_alphabetic)(s)
+/// }
+///
+/// assert_eq!(short_alpha(b"latin123"), Ok((&b"123"[..], &b"latin"[..])));
+/// assert_eq!(short_alpha(b"lengthy"), Ok((&b"y"[..], &b"length"[..])));
+/// assert_eq!(short_alpha(b"latin"), Err(Err::Incomplete(Needed::Size(1))));
+/// assert_eq!(short_alpha(b"ed"), Err(Err::Incomplete(Needed::Size(1))));
+/// assert_eq!(short_alpha(b"12345"), Err(Err::Error((&b"12345"[..], ErrorKind::TakeWhileMN))));
+/// ```
 pub fn take_while_m_n<F, Input, Error: ParseError<Input>>(m: usize, n: usize, cond: F) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTake + InputIter + InputLength + Slice<RangeFrom<usize>>,
@@ -135,6 +293,30 @@ where
   }
 }
 
+/// Returns the longest input slice (if any) till a predicate is met
+///
+/// The parser will return the longest slice till the given predicate *(a function that
+/// takes the input and returns a bool)*
+///
+/// # Streaming Specific
+/// *Streaming version* will return a `Err::Incomplete(Needed::Size(1))` if the match reaches the
+/// end of input or if there was not match
+///
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::streaming::take_till;
+///
+/// fn till_colon(s: &str) -> IResult<&str, &str> {
+///   take_till(|c| c == ':')(s)
+/// }
+///
+/// assert_eq!(till_colon("latin:123"), Ok((":123", "latin")));
+/// assert_eq!(till_colon(":empty matched"), Ok((":empty matched", ""))); //allowed
+/// assert_eq!(till_colon("12345"), Err(Err::Incomplete(Needed::Size(1))));
+/// assert_eq!(till_colon(""), Err(Err::Incomplete(Needed::Size(1))));
+/// ```
 pub fn take_till<F, Input, Error: ParseError<Input>>(cond: F) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTakeAtPosition,
@@ -143,6 +325,29 @@ where
   move |i: Input| i.split_at_position(|c| cond(c))
 }
 
+/// Returns the longest (atleast 1) input slice till a predicate is met
+///
+/// The parser will return the longest slice till the given predicate *(a function that
+/// takes the input and returns a bool)*
+///
+/// # Streaming Specific
+/// *Streaming version* will return a `Err::Incomplete(Needed::Size(1))` if the match reaches the
+/// end of input or if there was not match
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::streaming::take_till1;
+///
+/// fn till_colon(s: &str) -> IResult<&str, &str> {
+///   take_till1(|c| c == ':')(s)
+/// }
+///
+/// assert_eq!(till_colon("latin:123"), Ok((":123", "latin")));
+/// assert_eq!(till_colon(":empty matched"), Err(Err::Error((":empty matched", ErrorKind::TakeTill1))));
+/// assert_eq!(till_colon("12345"), Err(Err::Incomplete(Needed::Size(1))));
+/// assert_eq!(till_colon(""), Err(Err::Incomplete(Needed::Size(1))));
+/// ```
 pub fn take_till1<F, Input, Error: ParseError<Input>>(cond: F) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTakeAtPosition,
@@ -154,6 +359,26 @@ where
   }
 }
 
+/// Returns an input slice containing the first N input elements (Input[..N])
+///
+/// # Streaming Specific
+/// *Streaming version* will return a `Err::Incomplete(Needed::Size(N))` where N is the
+/// argument if the input is less than the length provided
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::streaming::take;
+///
+/// fn take6(s: &str) -> IResult<&str, &str> {
+///   take(6usize)(s)
+/// }
+///
+/// assert_eq!(take6("1234567"), Ok(("7", "123456")));
+/// assert_eq!(take6("things"), Ok(("", "things")));
+/// assert_eq!(take6("short"), Err(Err::Incomplete(Needed::Size(6)))); //N doesn't change
+/// assert_eq!(take6(""), Err(Err::Incomplete(Needed::Size(6))));
+/// ```
 pub fn take<C, Input, Error: ParseError<Input>>(count: C) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputIter + InputTake,
@@ -166,6 +391,27 @@ where
   }
 }
 
+/// Returns the longest input slice till it matches the pattern.
+///
+/// It doesn't consume the pattern
+///
+/// # Streaming Specific
+/// *Streaming version* will return a `Err::Incomplete(Needed::Size(N))` if the input doesn't
+/// contain the pattern or if the input is smaller than the pattern
+/// # Example
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// use nom::bytes::streaming::take_until;
+///
+/// fn until_eof(s: &str) -> IResult<&str, &str> {
+///   take_until("eof")(s)
+/// }
+///
+/// assert_eq!(until_eof("hello, worldeof"), Ok(("eof", "hello, world")));
+/// assert_eq!(until_eof("hello, world"), Err(Err::Incomplete(Needed::Size(3))));
+/// assert_eq!(until_eof(""), Err(Err::Incomplete(Needed::Size(3))));
+/// ```
 pub fn take_until<T, Input, Error: ParseError<Input>>(tag: T) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: InputTake + FindSubstring<T>,
@@ -183,6 +429,28 @@ where
   }
 }
 
+/// Matches a byte string with escaped characters.
+///
+/// * The first argument matches the normal characters (it must not accept the control character),
+/// * the second argument is the control character (like `\` in most languages),
+/// * the third argument matches the escaped characters
+///
+/// # Example
+/// ```
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
+/// # use nom::character::complete::digit1;
+/// use nom::bytes::streaming::escaped;
+/// use nom::character::streaming::one_of;
+///
+/// fn esc(s: &str) -> IResult<&str, &str> {
+///   escaped(digit1, '\\', one_of("\"n\\"))(s)
+/// }
+///
+/// assert_eq!(esc("123;"), Ok((";", "123")));
+/// assert_eq!(esc("12\\\"34;"), Ok((";", "12\\\"34")));
+/// ```
+///
 pub fn escaped<Input, Error, F, G, O1, O2>(normal: F, control_char: char, escapable: G) -> impl Fn(Input) -> IResult<Input, Input, Error>
 where
   Input: Clone + ::traits::Offset + InputLength + InputTake + InputTakeAtPosition + Slice<RangeFrom<usize>> + InputIter,
@@ -250,6 +518,16 @@ where
   escaped(normal, control_char, escapable)(i)
 }
 
+/// Matches a byte string with escaped characters.
+///
+/// * The first argument matches the normal characters (it must not match the control character),
+/// * the second argument is the control character (like `\` in most languages),
+/// * the third argument matches the escaped characters and transforms them.
+///
+/// As an example, the chain `abc\tdef` could be `abc    def` (it also consumes the control character)
+///
+/// # Example
+/// Currently Unavailable
 pub fn escaped_transform<Input, Error, F, G, O1, O2, ExtendItem, Output>(
   normal: F,
   control_char: char,
@@ -341,4 +619,4 @@ where
 {
   escaped_transform(normal, control_char, transform)(i)
 
-}
\ No newline at end of file
+}
diff --git a/src/character/mod.rs b/src/character/mod.rs
index 91ea8b8..3f0899a 100644
--- a/src/character/mod.rs
+++ b/src/character/mod.rs
@@ -9,36 +9,91 @@ pub mod streaming;
 pub mod complete;
 
 /// Tests if byte is ASCII alphabetic: A-Z, a-z
+///
+/// # Example
+///
+/// ```
+/// # use nom::character::is_alphabetic;
+/// assert_eq!(is_alphabetic(b'9'), false);
+/// assert_eq!(is_alphabetic(b'a'), true);
+/// ```
 #[inline]
 pub fn is_alphabetic(chr: u8) -> bool {
   (chr >= 0x41 && chr <= 0x5A) || (chr >= 0x61 && chr <= 0x7A)
 }
 
 /// Tests if byte is ASCII digit: 0-9
+///
+/// # Example
+///
+/// ```
+/// # use nom::character::is_digit;
+/// assert_eq!(is_digit(b'a'), false);
+/// assert_eq!(is_digit(b'9'), true);
+/// ```
 #[inline]
 pub fn is_digit(chr: u8) -> bool {
   chr >= 0x30 && chr <= 0x39
 }
 
 /// Tests if byte is ASCII hex digit: 0-9, A-F, a-f
+///
+/// # Example
+///
+/// ```
+/// # use nom::character::is_hex_digit;
+/// assert_eq!(is_hex_digit(b'a'), true);
+/// assert_eq!(is_hex_digit(b'9'), true);
+/// assert_eq!(is_hex_digit(b'A'), true);
+/// assert_eq!(is_hex_digit(b'x'), false);
+/// ```
 #[inline]
 pub fn is_hex_digit(chr: u8) -> bool {
   (chr >= 0x30 && chr <= 0x39) || (chr >= 0x41 && chr <= 0x46) || (chr >= 0x61 && chr <= 0x66)
 }
 
 /// Tests if byte is ASCII octal digit: 0-7
+///
+/// # Example
+///
+/// ```
+/// # use nom::character::is_oct_digit;
+/// assert_eq!(is_oct_digit(b'a'), false);
+/// assert_eq!(is_oct_digit(b'9'), false);
+/// assert_eq!(is_oct_digit(b'6'), true);
+/// ```
 #[inline]
 pub fn is_oct_digit(chr: u8) -> bool {
   chr >= 0x30 && chr <= 0x37
 }
 
 /// Tests if byte is ASCII alphanumeric: A-Z, a-z, 0-9
+///
+/// # Example
+///
+/// ```
+/// # use nom::character::is_alphanumeric;
+/// assert_eq!(is_alphanumeric(b'-'), false);
+/// assert_eq!(is_alphanumeric(b'a'), true);
+/// assert_eq!(is_alphanumeric(b'9'), true);
+/// assert_eq!(is_alphanumeric(b'A'), true);
+/// ```
 #[inline]
 pub fn is_alphanumeric(chr: u8) -> bool {
   is_alphabetic(chr) || is_digit(chr)
 }
 
 /// Tests if byte is ASCII space or tab
+///
+/// # Example
+///
+/// ```
+/// # use nom::character::is_space;
+/// assert_eq!(is_space(b'\n'), false);
+/// assert_eq!(is_space(b'\r'), false);
+/// assert_eq!(is_space(b' '), true);
+/// assert_eq!(is_space(b'\t'), true);
+/// ```
 #[inline]
 pub fn is_space(chr: u8) -> bool {
   chr == b' ' || chr == b'\t'
diff --git a/src/character/streaming.rs b/src/character/streaming.rs
index 556b96c..3142281 100644
--- a/src/character/streaming.rs
+++ b/src/character/streaming.rs
@@ -10,9 +10,21 @@ use traits::{Compare, CompareResult};
 
 use error::ErrorKind;
 
-/// Recognizes one character
+/// Recognizes one character.
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
+///
+/// # Example
+///
+/// ```
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::character::streaming::char;
+/// # fn main() {
+/// assert_eq!(char::<_, (_, ErrorKind)>('a')(&b"abc"[..]), Ok((&b"bc"[..], 'a')));
+/// assert_eq!(char::<_, (_, ErrorKind)>('a')(&b"bc"[..]), Err(Err::Error((&b"bc"[..], ErrorKind::Char))));
+/// assert_eq!(char::<_, (_, ErrorKind)>('a')(&b""[..]), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn char<I, Error: ParseError<I>>(c: char) -> impl Fn(I) -> IResult<I, char, Error>
 where
   I: Slice<RangeFrom<usize>> + InputIter,
@@ -30,9 +42,21 @@ where
   }
 }
 
-/// Recognizes one of the provided characters
+/// Recognizes one of the provided characters.
+///
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data
+/// # Example
+///
+/// ```
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::character::streaming::one_of;
+/// # fn main() {
+/// assert_eq!(one_of::<_, _, (_, ErrorKind)>("abc")("b"), Ok(("", 'b')));
+/// assert_eq!(one_of::<_, _, (_, ErrorKind)>("a")("bc"), Err(Err::Error(("bc", ErrorKind::OneOf))));
+/// assert_eq!(one_of::<_, _, (_, ErrorKind)>("a")(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn one_of<I, T, Error: ParseError<I>>(list: T) -> impl Fn(I) -> IResult<I, char, Error>
 where
   I: Slice<RangeFrom<usize>> + InputIter,
@@ -46,9 +70,21 @@ where
   }
 }
 
-/// Recognizes a character that is not in the provided characters
+/// Recognizes a character that is not in the provided characters.
+///
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
+///
+/// # Example
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data
+/// ```
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::character::streaming::none_of;
+/// # fn main() {
+/// assert_eq!(none_of::<_, _, (_, ErrorKind)>("abc")("z"), Ok(("", 'z')));
+/// assert_eq!(none_of::<_, _, (_, ErrorKind)>("ab")("a"), Err(Err::Error(("a", ErrorKind::NoneOf))));
+/// assert_eq!(none_of::<_, _, (_, ErrorKind)>("a")(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn none_of<I, T, Error: ParseError<I>>(list: T) -> impl Fn(I) -> IResult<I, char, Error>
 where
   I: Slice<RangeFrom<usize>> + InputIter,
@@ -62,9 +98,21 @@ where
   }
 }
 
-/// recognizes the string "\r\n"
+/// Recognizes the string "\r\n".
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
+///
+/// # Example
+///
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::crlf;
+/// # fn main() {
+/// assert_eq!(crlf::<_, (_, ErrorKind)>("\r\nc"), Ok(("c", "\r\n")));
+/// assert_eq!(crlf::<_, (_, ErrorKind)>("ab\r\nc"), Err(Err::Error(("ab\r\nc", ErrorKind::CrLf))));
+/// assert_eq!(crlf::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(2))));
+/// # }
+/// ```
 pub fn crlf<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: Slice<Range<usize>> + Slice<RangeFrom<usize>> + Slice<RangeTo<usize>>,
@@ -82,9 +130,21 @@ where
   }
 }
 
-/// recognizes a string of any char except '\r' or '\n'
+/// Recognizes a string of any char except '\r' or '\n'.
+///
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
+///
+/// # Example
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::not_line_ending;
+/// # fn main() {
+/// assert_eq!(not_line_ending::<_, (_, ErrorKind)>("ab\r\nc"), Ok(("\r\nc", "ab")));
+/// assert_eq!(not_line_ending::<_, (_, ErrorKind)>("abc"), Err(Err::Incomplete(Needed::Unknown)));
+/// assert_eq!(not_line_ending::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Unknown)));
+/// # }
+/// ```
 pub fn not_line_ending<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: Slice<Range<usize>> + Slice<RangeFrom<usize>> + Slice<RangeTo<usize>>,
@@ -122,9 +182,21 @@ where
   }
 }
 
-/// Recognizes an end of line (both '\n' and '\r\n')
+/// Recognizes an end of line (both '\n' and '\r\n').
+///
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data
+/// # Example
+///
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::line_ending;
+/// # fn main() {
+/// assert_eq!(line_ending::<_, (_, ErrorKind)>("\r\nc"), Ok(("c", "\r\n")));
+/// assert_eq!(line_ending::<_, (_, ErrorKind)>("ab\r\nc"), Err(Err::Error(("ab\r\nc", ErrorKind::CrLf))));
+/// assert_eq!(line_ending::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn line_ending<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: Slice<Range<usize>> + Slice<RangeFrom<usize>> + Slice<RangeTo<usize>>,
@@ -145,9 +217,21 @@ where
   }
 }
 
-/// matches a newline character '\\n'
+/// Matches a newline character '\\n'.
+///
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data
+/// # Example
+///
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::newline;
+/// # fn main() {
+/// assert_eq!(newline::<_, (_, ErrorKind)>("\nc"), Ok(("c", '\n')));
+/// assert_eq!(newline::<_, (_, ErrorKind)>("\r\nc"), Err(Err::Error(("\r\nc", ErrorKind::Char))));
+/// assert_eq!(newline::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn newline<I, Error: ParseError<I>>(input: I) -> IResult<I, char, Error>
 where
   I: Slice<RangeFrom<usize>> + InputIter,
@@ -156,9 +240,21 @@ where
   char('\n')(input)
 }
 
-/// matches a tab character '\t'
+/// Matches a tab character '\t'.
+///
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
+///
+/// # Example
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::tab;
+/// # fn main() {
+/// assert_eq!(tab::<_, (_, ErrorKind)>("\tc"), Ok(("c", '\t')));
+/// assert_eq!(tab::<_, (_, ErrorKind)>("\r\nc"), Err(Err::Error(("\r\nc", ErrorKind::Char))));
+/// assert_eq!(tab::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn tab<I, Error: ParseError<I>>(input: I) -> IResult<I, char, Error>
 where
   I: Slice<RangeFrom<usize>> + InputIter,
@@ -167,19 +263,20 @@ where
   char('\t')(input)
 }
 
-/// matches one byte as a character. Note that the input type will
+/// Matches one byte as a character. Note that the input type will
 /// accept a `str`, but not a `&[u8]`, unlike many other nom parsers.
 ///
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
+///
 /// # Example
+///
 /// ```
-/// # #[macro_use] extern crate nom;
-/// # use nom::{character::streaming::anychar, error::ErrorKind};
+/// # use nom::{character::streaming::anychar, Err, error::ErrorKind, IResult, Needed};
 /// # fn main() {
-/// assert_eq!(anychar::<_,(&str, ErrorKind)>("abc"), Ok(("bc",'a')));
+/// assert_eq!(anychar::<_, (_, ErrorKind)>("abc"), Ok(("bc",'a')));
+/// assert_eq!(anychar::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
 /// # }
 /// ```
-///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data
 pub fn anychar<T, E: ParseError<T>>(input: T) -> IResult<T, char, E>
 where
   T: InputIter + InputLength + Slice<RangeFrom<usize>>,
@@ -196,11 +293,24 @@ where
 }
 
 /// Recognizes zero or more lowercase and uppercase alphabetic characters.
-/// For ASCII strings: a-zA-Z
-/// For UTF8 strings, any alphabetic code point (ie, not only the ASCII ones)
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
-/// or if no terminating token is found (a non alphabetic character)
+/// * For ASCII strings: a-zA-Z
+/// * For UTF8 strings, any alphabetic code point (ie, not only the ASCII ones)
+///
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
+/// or if no terminating token is found (a non alphabetic character).
+///
+/// # Example
+///
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::alpha0;
+/// # fn main() {
+/// assert_eq!(alpha0::<_, (_, ErrorKind)>("ab1c"), Ok(("1c", "ab")));
+/// assert_eq!(alpha0::<_, (_, ErrorKind)>("1c"), Ok(("1c", "")));
+/// assert_eq!(alpha0::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn alpha0<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: InputTakeAtPosition,
@@ -209,12 +319,25 @@ where
   input.split_at_position(|item| !item.is_alpha())
 }
 
-/// Recognizes one or more lowercase and uppercase alphabetic characters
-/// For ASCII strings: a-zA-Z
-/// For UTF8 strings, any alphabetic code point (ie, not only the ASCII ones)
+/// Recognizes one or more lowercase and uppercase alphabetic characters.
+///
+/// * For ASCII strings: a-zA-Z
+/// * For UTF8 strings, any alphabetic code point (ie, not only the ASCII ones)
+///
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
+/// or if no terminating token is found (a non alphabetic character).
+///
+/// # Example
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
-/// or if no terminating token is found (a non alphabetic character)
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::alpha1;
+/// # fn main() {
+/// assert_eq!(alpha1::<_, (_, ErrorKind)>("aB1c"), Ok(("1c", "aB")));
+/// assert_eq!(alpha1::<_, (_, ErrorKind)>("1c"), Err(Err::Error(("1c", ErrorKind::Alpha))));
+/// assert_eq!(alpha1::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn alpha1<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: InputTakeAtPosition,
@@ -225,8 +348,20 @@ where
 
 /// Recognizes zero or more numerical characters: 0-9
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
-/// or if no terminating token is found (a non digit character)
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
+/// or if no terminating token is found (a non digit character).
+///
+/// # Example
+///
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::digit0;
+/// # fn main() {
+/// assert_eq!(digit0::<_, (_, ErrorKind)>("21c"), Ok(("c", "21")));
+/// assert_eq!(digit0::<_, (_, ErrorKind)>("a21c"), Ok(("a21c", "")));
+/// assert_eq!(digit0::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn digit0<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: InputTakeAtPosition,
@@ -237,8 +372,20 @@ where
 
 /// Recognizes one or more numerical characters: 0-9
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
-/// or if no terminating token is found (a non digit character)
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
+/// or if no terminating token is found (a non digit character).
+///
+/// # Example
+///
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::digit1;
+/// # fn main() {
+/// assert_eq!(digit1::<_, (_, ErrorKind)>("21c"), Ok(("c", "21")));
+/// assert_eq!(digit1::<_, (_, ErrorKind)>("c1"), Err(Err::Error(("c1", ErrorKind::Digit))));
+/// assert_eq!(digit1::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn digit1<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: InputTakeAtPosition,
@@ -249,8 +396,20 @@ where
 
 /// Recognizes zero or more hexadecimal numerical characters: 0-9, A-F, a-f
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
-/// or if no terminating token is found (a non hexadecimal digit character)
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
+/// or if no terminating token is found (a non hexadecimal digit character).
+///
+/// # Example
+///
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::hex_digit0;
+/// # fn main() {
+/// assert_eq!(hex_digit0::<_, (_, ErrorKind)>("21cZ"), Ok(("Z", "21c")));
+/// assert_eq!(hex_digit0::<_, (_, ErrorKind)>("Z21c"), Ok(("Z21c", "")));
+/// assert_eq!(hex_digit0::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn hex_digit0<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: InputTakeAtPosition,
@@ -261,8 +420,20 @@ where
 
 /// Recognizes one or more hexadecimal numerical characters: 0-9, A-F, a-f
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
-/// or if no terminating token is found (a non hexadecimal digit character)
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
+/// or if no terminating token is found (a non hexadecimal digit character).
+///
+/// # Example
+///
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::hex_digit1;
+/// # fn main() {
+/// assert_eq!(hex_digit1::<_, (_, ErrorKind)>("21cZ"), Ok(("Z", "21c")));
+/// assert_eq!(hex_digit1::<_, (_, ErrorKind)>("H2"), Err(Err::Error(("H2", ErrorKind::HexDigit))));
+/// assert_eq!(hex_digit1::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn hex_digit1<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: InputTakeAtPosition,
@@ -273,8 +444,20 @@ where
 
 /// Recognizes zero or more octal characters: 0-7
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
-/// or if no terminating token is found (a non octal digit character)
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
+/// or if no terminating token is found (a non octal digit character).
+///
+/// # Example
+///
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::oct_digit0;
+/// # fn main() {
+/// assert_eq!(oct_digit0::<_, (_, ErrorKind)>("21cZ"), Ok(("cZ", "21")));
+/// assert_eq!(oct_digit0::<_, (_, ErrorKind)>("Z21c"), Ok(("Z21c", "")));
+/// assert_eq!(oct_digit0::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn oct_digit0<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: InputTakeAtPosition,
@@ -284,9 +467,21 @@ where
 }
 
 /// Recognizes one or more octal characters: 0-7
-////
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
-/// or if no terminating token is found (a non octal digit character)
+///
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
+/// or if no terminating token is found (a non octal digit character).
+///
+/// # Example
+///
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::oct_digit1;
+/// # fn main() {
+/// assert_eq!(oct_digit1::<_, (_, ErrorKind)>("21cZ"), Ok(("cZ", "21")));
+/// assert_eq!(oct_digit1::<_, (_, ErrorKind)>("H2"), Err(Err::Error(("H2", ErrorKind::OctDigit))));
+/// assert_eq!(oct_digit1::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn oct_digit1<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: InputTakeAtPosition,
@@ -296,11 +491,24 @@ where
 }
 
 /// Recognizes zero or more numerical and alphabetic characters.
-/// For ASCII strings: 0-9a-zA-Z
-/// For UTF8 strings, 0-9 and any alphabetic code point (ie, not only the ASCII ones)
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
-/// or if no terminating token is found (a non alphanumerical character)
+/// * For ASCII strings: 0-9a-zA-Z
+/// * For UTF8 strings, 0-9 and any alphabetic code point (ie, not only the ASCII ones)
+///
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
+/// or if no terminating token is found (a non alphanumerical character).
+///
+/// # Example
+///
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::alphanumeric0;
+/// # fn main() {
+/// assert_eq!(alphanumeric0::<_, (_, ErrorKind)>("21cZ%1"), Ok(("%1", "21cZ")));
+/// assert_eq!(alphanumeric0::<_, (_, ErrorKind)>("&Z21c"), Ok(("&Z21c", "")));
+/// assert_eq!(alphanumeric0::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn alphanumeric0<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: InputTakeAtPosition,
@@ -310,11 +518,24 @@ where
 }
 
 /// Recognizes one or more numerical and alphabetic characters.
-/// For ASCII strings: 0-9a-zA-Z
-/// For UTF8 strings, 0-9 and any alphabetic code point (ie, not only the ASCII ones)
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
-/// or if no terminating token is found (a non alphanumerical character)
+/// * For ASCII strings: 0-9a-zA-Z
+/// * For UTF8 strings, 0-9 and any alphabetic code point (ie, not only the ASCII ones)
+///
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
+/// or if no terminating token is found (a non alphanumerical character).
+///
+/// # Example
+///
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::alphanumeric1;
+/// # fn main() {
+/// assert_eq!(alphanumeric1::<_, (_, ErrorKind)>("21cZ%1"), Ok(("%1", "21cZ")));
+/// assert_eq!(alphanumeric1::<_, (_, ErrorKind)>("&H2"), Err(Err::Error(("&H2", ErrorKind::AlphaNumeric))));
+/// assert_eq!(alphanumeric1::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn alphanumeric1<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: InputTakeAtPosition,
@@ -323,10 +544,22 @@ where
   input.split_at_position1(|item| !item.is_alphanum(), ErrorKind::AlphaNumeric)
 }
 
-/// Recognizes zero or more spaces and tabs
+/// Recognizes zero or more spaces and tabs.
+///
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
+/// or if no terminating token is found (a non space character).
+///
+/// # Example
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
-/// or if no terminating token is found (a non space character)
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::space0;
+/// # fn main() {
+/// assert_eq!(space0::<_, (_, ErrorKind)>(" \t21c"), Ok(("21c", " \t")));
+/// assert_eq!(space0::<_, (_, ErrorKind)>("Z21c"), Ok(("Z21c", "")));
+/// assert_eq!(space0::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn space0<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: InputTakeAtPosition,
@@ -337,10 +570,22 @@ where
     !(c == ' ' || c == '\t')
   })
 }
-/// Recognizes one or more spaces and tabs
+/// Recognizes one or more spaces and tabs.
+///
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
+/// or if no terminating token is found (a non space character).
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
-/// or if no terminating token is found (a non space character)
+/// # Example
+///
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::space1;
+/// # fn main() {
+/// assert_eq!(space1::<_, (_, ErrorKind)>(" \t21c"), Ok(("21c", " \t")));
+/// assert_eq!(space1::<_, (_, ErrorKind)>("H2"), Err(Err::Error(("H2", ErrorKind::Space))));
+/// assert_eq!(space1::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn space1<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: InputTakeAtPosition,
@@ -355,10 +600,22 @@ where
   )
 }
 
-/// Recognizes zero or more spaces, tabs, carriage returns and line feeds
+/// Recognizes zero or more spaces, tabs, carriage returns and line feeds.
+///
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
+/// or if no terminating token is found (a non space character).
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
-/// or if no terminating token is found (a non space character)
+/// # Example
+///
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::multispace0;
+/// # fn main() {
+/// assert_eq!(multispace0::<_, (_, ErrorKind)>(" \t\n\r21c"), Ok(("21c", " \t\n\r")));
+/// assert_eq!(multispace0::<_, (_, ErrorKind)>("Z21c"), Ok(("Z21c", "")));
+/// assert_eq!(multispace0::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn multispace0<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: InputTakeAtPosition,
@@ -370,10 +627,22 @@ where
   })
 }
 
-/// Recognizes one or more spaces, tabs, carriage returns and line feeds
+/// Recognizes one or more spaces, tabs, carriage returns and line feeds.
+///
+/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
+/// or if no terminating token is found (a non space character).
+///
+/// # Example
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
-/// or if no terminating token is found (a non space character)
+/// ```
+/// # use nom::{Err, error::ErrorKind, IResult, Needed};
+/// # use nom::character::streaming::multispace1;
+/// # fn main() {
+/// assert_eq!(multispace1::<_, (_, ErrorKind)>(" \t\n\r21c"), Ok(("21c", " \t\n\r")));
+/// assert_eq!(multispace1::<_, (_, ErrorKind)>("H2"), Err(Err::Error(("H2", ErrorKind::MultiSpace))));
+/// assert_eq!(multispace1::<_, (_, ErrorKind)>(""), Err(Err::Incomplete(Needed::Size(1))));
+/// # }
+/// ```
 pub fn multispace1<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
 where
   T: InputTakeAtPosition,
diff --git a/src/combinator/macros.rs b/src/combinator/macros.rs
index 66872fe..9b5974a 100644
--- a/src/combinator/macros.rs
+++ b/src/combinator/macros.rs
@@ -715,7 +715,7 @@ macro_rules! map_res_err (
   (__impl $i:expr, $submac:ident!( $($args:tt)* ), $submac2:ident!( $($args2:tt)* )) => (
     {
       use $crate::lib::std::result::Result::*;
-      use $crate::Convert, Err};
+      use $crate::Err;
 
       let i_ = $i.clone();
       match $submac!(i_, $($args)*) {
@@ -1182,7 +1182,7 @@ macro_rules! cond_reduce(
   ($i:expr, $cond:expr, $submac:ident!( $($args:tt)* )) => (
     {
       use $crate::lib::std::result::Result::*;
-      use $crate::{Convert,Err,ErrorKind,IResult};
+      use $crate::{Err,error::ErrorKind,IResult};
       let default_err = Err(Err::convert(Err::Error(error_position!($i, ErrorKind::CondReduce))));
 
       if $cond {
@@ -1223,7 +1223,7 @@ macro_rules! peek(
   ($i:expr, $submac:ident!( $($args:tt)* )) => (
     {
       use $crate::lib::std::result::Result::*;
-      use $crate::{Convert,Err};
+      use $crate::Err;
 
       let i_ = $i.clone();
       match $submac!(i_, $($args)*) {
@@ -1309,7 +1309,7 @@ macro_rules! tap (
   ($i:expr, $name:ident : $submac:ident!( $($args:tt)* ) => $e:expr) => (
     {
       use $crate::lib::std::result::Result::*;
-      use $crate::{Convert,Err,Needed,IResult};
+      use $crate::{Err,Needed,IResult};
 
       match $submac!($i, $($args)*) {
         Ok((i,o)) => {
@@ -1614,7 +1614,6 @@ mod tests {
 
   #[test]
   fn parse_to() {
-    //use util::Convert;
     let res: IResult<_, _, (&str, ErrorKind)> = parse_to!("ab", usize);
 
     assert_eq!(
diff --git a/src/combinator/mod.rs b/src/combinator/mod.rs
index 332e898..762bfdb 100644
--- a/src/combinator/mod.rs
+++ b/src/combinator/mod.rs
@@ -19,10 +19,12 @@ use lib::std::mem::transmute;
 mod macros;
 
 #[inline]
+// FIXME: remove?
 pub fn begin(input: &[u8]) -> IResult<(), &[u8]> {
   Ok(((), input))
 }
 
+// FIXME: remove?
 pub fn sized_buffer<'a, E: ParseError<&'a[u8]>>(input: &'a[u8]) -> IResult<&'a[u8], &'a[u8], E> {
   if input.is_empty() {
     return Err(Err::Incomplete(Needed::Unknown));
@@ -162,6 +164,27 @@ where
   map_res(first, second)(input)
 }
 
+/// applies a function returning an Option over the result of a parser
+///
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err,error::ErrorKind, IResult};
+/// use nom::character::complete::digit1;
+/// use nom::combinator::map_opt;
+/// # fn main() {
+///
+/// let parse = map_opt(digit1, |s: &str| s.parse::<u8>().ok());
+///
+/// // the parser will convert the result of digit1 to a number
+/// assert_eq!(parse("123"), Ok(("", 123)));
+///
+/// // this will fail if digit1 fails
+/// assert_eq!(parse("abc"), Err(Err::Error(("abc", ErrorKind::Digit))));
+///
+/// // this will fail if the mapped function fails (a `u8` is too small to hold `123456`)
+/// assert_eq!(parse("123456"), Err(Err::Error(("123456", ErrorKind::MapOpt))));
+/// # }
+/// ```
 pub fn map_opt<I: Clone, O1, O2, E: ParseError<I>, F, G>(first: F, second: G) -> impl Fn(I) -> IResult<I, O2, E>
 where
   F: Fn(I) -> IResult<I, O1, E>,
@@ -186,6 +209,7 @@ where
   map_opt(first, second)(input)
 }
 
+/// applies a parser over the result of another one
 pub fn map_parser<I: Clone, O1, O2, E: ParseError<I>, F, G>(first: F, second: G) -> impl Fn(I) -> IResult<I, O2, E>
 where
   F: Fn(I) -> IResult<I, O1, E>,
@@ -221,6 +245,7 @@ where
   }
 }
 
+/// optional parser: will return None if not successful
 pub fn opt<I:Clone, O, E: ParseError<I>, F>(f: F) -> impl Fn(I) -> IResult<I, Option<O>, E>
 where
   F: Fn(I) -> IResult<I, O, E>,
@@ -235,6 +260,7 @@ where
   }
 }
 
+/// transforms Incomplete into Error
 pub fn complete<I: Clone, O, E: ParseError<I>, F>(f: F) -> impl Fn(I) -> IResult<I, O, E>
 where
   F: Fn(I) -> IResult<I, O, E>,
@@ -258,6 +284,7 @@ where
     complete(f)(input)
 }
 
+/// succeeds if all the input has been consumed
 pub fn all_consuming<I, O, E: ParseError<I>, F>(f: F) -> impl Fn(I) -> IResult<I, O, E>
 where
   I: InputLength,
diff --git a/src/error.rs b/src/error.rs
index 60d1d6e..9d40b49 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -53,14 +53,20 @@ pub fn append_error<I, E: ParseError<I>>(input: I, kind: ErrorKind, other: E) ->
 #[cfg(feature = "alloc")]
 #[derive(Clone,Debug,PartialEq)]
 pub struct VerboseError<I> {
+  /// list of errors accumulated by `VerboseError`, containing the affected
+  /// part of input data, and some context
   pub errors: ::lib::std::vec::Vec<(I, VerboseErrorKind)>,
 }
 
 #[cfg(feature = "alloc")]
 #[derive(Clone,Debug,PartialEq)]
+/// error context for `VerboseError`
 pub enum VerboseErrorKind {
+  /// static string added by the `context` function
   Context(&'static str),
+  /// indicates which character was expected by the `char` function
   Char(char),
+  /// error kind given by various nom parsers
   Nom(ErrorKind),
 }
 
@@ -110,9 +116,8 @@ where
 /// indicates which parser returned an error
 #[cfg_attr(rustfmt, rustfmt_skip)]
 #[derive(Debug,PartialEq,Eq,Hash,Clone,Copy)]
-#[allow(deprecated)]
+#[allow(deprecated,missing_docs)]
 pub enum ErrorKind {
-  //Custom(E),
   Tag,
   MapRes,
   MapOpt,
@@ -125,10 +130,7 @@ pub enum ErrorKind {
   Many1,
   ManyTill,
   Count,
-  TakeUntilAndConsume,
   TakeUntil,
-  TakeUntilEitherAndConsume,
-  TakeUntilEither,
   LengthValue,
   TagClosure,
   Alpha,
@@ -159,25 +161,12 @@ pub enum ErrorKind {
   Fix,
   Escaped,
   EscapedTransform,
-  #[deprecated(since = "4.0.0", note = "Please use `Tag` instead")]
-  TagStr,
-  #[deprecated(since = "4.0.0", note = "Please use `IsNot` instead")]
-  IsNotStr,
-  #[deprecated(since = "4.0.0", note = "Please use `IsA` instead")]
-  IsAStr,
-  #[deprecated(since = "4.0.0", note = "Please use `TakeWhile1` instead")]
-  TakeWhile1Str,
   NonEmpty,
   ManyMN,
-  #[deprecated(since = "4.0.0", note = "Please use `TakeUntilAndConsume` instead")]
-  TakeUntilAndConsumeStr,
-  #[deprecated(since = "4.0.0", note = "Please use `TakeUntil` instead")]
-  TakeUntilStr,
   Not,
   Permutation,
   Verify,
   TakeTill1,
-  TakeUntilAndConsume1,
   TakeWhileMN,
   ParseTo,
   TooLarge,
@@ -188,9 +177,9 @@ pub enum ErrorKind {
 
 #[cfg_attr(rustfmt, rustfmt_skip)]
 #[allow(deprecated)]
+/// converts an ErrorKind to a number
 pub fn error_to_u32(e: &ErrorKind) -> u32 {
   match *e {
-    //ErrorKind::Custom(_)                 => 0,
     ErrorKind::Tag                       => 1,
     ErrorKind::MapRes                    => 2,
     ErrorKind::MapOpt                    => 3,
@@ -201,10 +190,7 @@ pub fn error_to_u32(e: &ErrorKind) -> u32 {
     ErrorKind::SeparatedNonEmptyList     => 8,
     ErrorKind::Many1                     => 9,
     ErrorKind::Count                     => 10,
-    ErrorKind::TakeUntilAndConsume       => 11,
     ErrorKind::TakeUntil                 => 12,
-    ErrorKind::TakeUntilEitherAndConsume => 13,
-    ErrorKind::TakeUntilEither           => 14,
     ErrorKind::LengthValue               => 15,
     ErrorKind::TagClosure                => 16,
     ErrorKind::Alpha                     => 17,
@@ -233,15 +219,9 @@ pub fn error_to_u32(e: &ErrorKind) -> u32 {
     ErrorKind::Fix                       => 49,
     ErrorKind::Escaped                   => 50,
     ErrorKind::EscapedTransform          => 51,
-    ErrorKind::TagStr                    => 52,
-    ErrorKind::IsNotStr                  => 53,
-    ErrorKind::IsAStr                    => 54,
-    ErrorKind::TakeWhile1Str             => 55,
     ErrorKind::NonEmpty                  => 56,
     ErrorKind::ManyMN                    => 57,
-    ErrorKind::TakeUntilAndConsumeStr    => 58,
     ErrorKind::HexDigit                  => 59,
-    ErrorKind::TakeUntilStr              => 60,
     ErrorKind::OctDigit                  => 61,
     ErrorKind::Many0                     => 62,
     ErrorKind::Not                       => 63,
@@ -249,7 +229,6 @@ pub fn error_to_u32(e: &ErrorKind) -> u32 {
     ErrorKind::ManyTill                  => 65,
     ErrorKind::Verify                    => 66,
     ErrorKind::TakeTill1                 => 67,
-    ErrorKind::TakeUntilAndConsume1      => 68,
     ErrorKind::TakeWhileMN               => 69,
     ErrorKind::ParseTo                   => 70,
     ErrorKind::TooLarge                  => 71,
@@ -262,9 +241,9 @@ pub fn error_to_u32(e: &ErrorKind) -> u32 {
 impl ErrorKind {
   #[cfg_attr(rustfmt, rustfmt_skip)]
   #[allow(deprecated)]
+  /// converts an ErrorKind to a text description
   pub fn description(&self) -> &str {
     match *self {
-      //ErrorKind::Custom(_)                 => "Custom error",
       ErrorKind::Tag                       => "Tag",
       ErrorKind::MapRes                    => "Map on Result",
       ErrorKind::MapOpt                    => "Map on Option",
@@ -276,10 +255,7 @@ impl ErrorKind {
       ErrorKind::Many0                     => "Many0",
       ErrorKind::Many1                     => "Many1",
       ErrorKind::Count                     => "Count",
-      ErrorKind::TakeUntilAndConsume       => "Take until and consume",
       ErrorKind::TakeUntil                 => "Take until",
-      ErrorKind::TakeUntilEitherAndConsume => "Take until either and consume",
-      ErrorKind::TakeUntilEither           => "Take until either",
       ErrorKind::LengthValue               => "Length followed by value",
       ErrorKind::TagClosure                => "Tag closure",
       ErrorKind::Alpha                     => "Alphabetic",
@@ -308,22 +284,15 @@ impl ErrorKind {
       ErrorKind::Fix                       => "Fix",
       ErrorKind::Escaped                   => "Escaped",
       ErrorKind::EscapedTransform          => "EscapedTransform",
-      ErrorKind::TagStr                    => "Tag on strings",
-      ErrorKind::IsNotStr                  => "IsNot on strings",
-      ErrorKind::IsAStr                    => "IsA on strings",
-      ErrorKind::TakeWhile1Str             => "TakeWhile1 on strings",
       ErrorKind::NonEmpty                  => "NonEmpty",
       ErrorKind::ManyMN                    => "Many(m, n)",
-      ErrorKind::TakeUntilAndConsumeStr    => "Take until and consume on strings",
       ErrorKind::HexDigit                  => "Hexadecimal Digit",
-      ErrorKind::TakeUntilStr              => "Take until on strings",
       ErrorKind::OctDigit                  => "Octal digit",
       ErrorKind::Not                       => "Negation",
       ErrorKind::Permutation               => "Permutation",
       ErrorKind::ManyTill                  => "ManyTill",
       ErrorKind::Verify                    => "predicate verification",
       ErrorKind::TakeTill1                 => "TakeTill1",
-      ErrorKind::TakeUntilAndConsume1      => "Take at least 1 until and consume",
       ErrorKind::TakeWhileMN               => "TakeWhileMN",
       ErrorKind::ParseTo                   => "Parse string to the specified type",
       ErrorKind::TooLarge                  => "Needed data size is too large",
diff --git a/src/internal.rs b/src/internal.rs
index 08922ec..416e601 100644
--- a/src/internal.rs
+++ b/src/internal.rs
@@ -64,6 +64,7 @@ pub enum Err<E> {
 }
 
 impl<E> Err<E> {
+  /// tests if the result is Incomplete
   pub fn is_incomplete(&self) -> bool {
     if let Err::Incomplete(_) = self {
       true
@@ -71,6 +72,16 @@ impl<E> Err<E> {
       false
     }
   }
+
+  /// automatically converts between errors if the underlying type supports it
+  pub fn convert<F>(e: Err<F>) -> Self
+    where E: From<F> {
+    match e {
+      Err::Incomplete(n) => Err::Incomplete(n),
+      Err::Failure(c) => Err::Failure(c.into()),
+      Err::Error(c) => Err::Error(c.into()),
+    }
+  }
 }
 
 /*
@@ -109,18 +120,6 @@ where
 }
 */
 
-use util::Convert;
-
-impl<F, E: From<F>> Convert<Err<F>> for Err<E> {
-  fn convert(e: Err<F>) -> Self {
-    match e {
-      Err::Incomplete(n) => Err::Incomplete(n),
-      Err::Failure(c) => Err::Failure(c.into()),
-      Err::Error(c) => Err::Error(c.into()),
-    }
-  }
-}
-
 #[cfg(test)]
 mod tests {
   use super::*;
diff --git a/src/lib.rs b/src/lib.rs
index 7df7106..35d8543 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -389,6 +389,8 @@ pub mod lib {
     pub use alloc::{boxed, string, vec};
 
     pub use core::{cmp, convert, fmt, iter, mem, ops, option, result, slice, str};
+
+    /// internal reproduction of std prelude
     pub mod prelude {
       pub use core::prelude as v1;
     }
@@ -398,6 +400,8 @@ pub mod lib {
   /// internal std exports for no_std compatibility
   pub mod std {
     pub use std::{alloc, boxed, cmp, collections, convert, fmt, hash, iter, mem, ops, option, result, slice, str, string, vec};
+
+    /// internal reproduction of std prelude
     pub mod prelude {
       pub use std::prelude as v1;
     }
diff --git a/src/multi/macros.rs b/src/multi/macros.rs
index a612508..9019c92 100644
--- a/src/multi/macros.rs
+++ b/src/multi/macros.rs
@@ -317,7 +317,7 @@ macro_rules! length_count(
   ($i:expr, $submac:ident!( $($args:tt)* ), $submac2:ident!( $($args2:tt)* )) => (
     {
       use $crate::lib::std::result::Result::*;
-      use $crate::{Err,Convert};
+      use $crate::Err;
 
       match $submac!($i, $($args)*) {
         Err(e)     => Err(Err::convert(e)),
@@ -352,7 +352,7 @@ macro_rules! length_count(
 macro_rules! length_data(
   ($i:expr, $submac:ident!( $($args:tt)* )) => ({
     use $crate::lib::std::result::Result::*;
-    use $crate::{Convert,Err};
+    use $crate::Err;
 
     match $submac!($i, $($args)*) {
       Err(e)     => Err(e),
diff --git a/src/multi/mod.rs b/src/multi/mod.rs
index 07b93df..3f5478d 100644
--- a/src/multi/mod.rs
+++ b/src/multi/mod.rs
@@ -15,25 +15,19 @@ use error::ErrorKind;
 /// # Arguments
 /// * `f` The parser to apply.
 /// ```rust
-/// # #[macro_use] extern crate nom;
-/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
 /// use nom::multi::many0;
 /// use nom::bytes::complete::tag;
-/// # fn main() {
-/// let embedded_parser = |s: &'static str| {
-///   tag::<_, _, (_, ErrorKind)>("abc")(s)
-/// };
-/// let parser = |s: &'static str| {
-///   many0::<_, _, (_, ErrorKind), _>(embedded_parser)(s)
-/// };
+///
+/// fn parser(s: &str) -> IResult<&str, Vec<&str>> {
+///   many0(tag("abc"))(s)
+/// }
 ///
 /// assert_eq!(parser("abcabc"), Ok(("", vec!["abc", "abc"])));
 /// assert_eq!(parser("abc123"), Ok(("123", vec!["abc"])));
 /// assert_eq!(parser("123123"), Ok(("123123", vec![])));
 /// assert_eq!(parser(""), Ok(("", vec![])));
-/// # }
 /// ```
-//FIXME: streaming
 #[cfg(feature = "alloc")]
 pub fn many0<I, O, E, F>(f: F) -> impl Fn(I) -> IResult<I, Vec<O>, E>
 where
@@ -60,7 +54,6 @@ where
     }
   }
 }
-//FIXME: streaming
 // this implementation is used for type inference issues in macros
 #[doc(hidden)]
 #[cfg(feature = "alloc")]
@@ -80,25 +73,19 @@ where
 /// # Arguments
 /// * `f` The parser to apply.
 /// ```rust
-/// # #[macro_use] extern crate nom;
-/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
 /// use nom::multi::many1;
 /// use nom::bytes::complete::tag;
-/// # fn main() {
-/// let embedded_parser = |s: &'static str| {
-///   tag::<_, _, (_, ErrorKind)>("abc")(s)
-/// };
-/// let parser = |s: &'static str| {
-///   many1::<_, _, (_, ErrorKind), _>(embedded_parser)(s)
-/// };
+///
+/// fn parser(s: &str) -> IResult<&str, Vec<&str>> {
+///   many1(tag("abc"))(s)
+/// }
 ///
 /// assert_eq!(parser("abcabc"), Ok(("", vec!["abc", "abc"])));
 /// assert_eq!(parser("abc123"), Ok(("123", vec!["abc"])));
 /// assert_eq!(parser("123123"), Err(Err::Error(("123123", ErrorKind::Tag))));
 /// assert_eq!(parser(""), Err(Err::Error(("", ErrorKind::Tag))));
-/// # }
 /// ```
-//FIXME: streaming
 #[cfg(feature = "alloc")]
 pub fn many1<I, O, E, F>(f: F) -> impl Fn(I) -> IResult<I, Vec<O>, E>
 where
@@ -135,7 +122,6 @@ where
   }
 }
 
-//FIXME: streaming
 // this implementation is used for type inference issues in macros
 #[doc(hidden)]
 #[cfg(feature = "alloc")]
@@ -152,19 +138,12 @@ where
 /// a result. Returns a pair consisting of the results of
 /// `f` in a `Vec` and the result of `g`.
 /// ```rust
-/// # #[macro_use] extern crate nom;
-/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
 /// use nom::multi::many_till;
 /// use nom::bytes::complete::tag;
-/// # fn main() {
-/// let condition_parser = |s: &'static str| {
-///   tag::<_, _, (_, ErrorKind)>("end")(s)
-/// };
-/// let embedded_parser = |s: &'static str| {
-///   tag::<_, _, (_, ErrorKind)>("abc")(s)
-/// };
-/// let parser = |s: &'static str| {
-///   many_till::<_, _, _, (_, ErrorKind), _, _>(embedded_parser, condition_parser)(s)
+///
+/// fn parser(s: &str) -> IResult<&str, (Vec<&str>, &str)> {
+///   many_till(tag("abc"), tag("end"))(s)
 /// };
 ///
 /// assert_eq!(parser("abcabcend"), Ok(("", (vec!["abc", "abc"], "end"))));
@@ -172,9 +151,7 @@ where
 /// assert_eq!(parser("123123end"), Err(Err::Error(("123123end", ErrorKind::Tag))));
 /// assert_eq!(parser(""), Err(Err::Error(("", ErrorKind::Tag))));
 /// assert_eq!(parser("abcendefg"), Ok(("efg", (vec!["abc"], "end"))));
-/// # }
 /// ```
-//FIXME: streaming
 #[cfg(feature = "alloc")]
 pub fn many_till<I, O, P, E, F, G>(f: F, g: G) -> impl Fn(I) -> IResult<I, (Vec<O>, P), E>
 where
@@ -211,7 +188,6 @@ where
   }
 }
 
-//FIXME: streaming
 // this implementation is used for type inference issues in macros
 #[doc(hidden)]
 #[cfg(feature = "alloc")]
@@ -231,29 +207,20 @@ where
 /// * `f` Parses the elements of the list.
 /// * `sep` Parses the separator between list elements.
 /// ```rust
-/// # #[macro_use] extern crate nom;
-/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
 /// use nom::multi::separated_list;
 /// use nom::bytes::complete::tag;
-/// # fn main() {
-/// let separator_parser = |s: &'static str| {
-///   tag::<_, _, (_, ErrorKind)>("|")(s)
-/// };
-/// let embedded_parser = |s: &'static str| {
-///   tag::<_, _, (_, ErrorKind)>("abc")(s)
-/// };
-/// let parser = |s: &'static str| {
-///   separated_list::<_, _, _, (_, ErrorKind), _, _>(separator_parser, embedded_parser)(s)
-/// };
+///
+/// fn parser(s: &str) -> IResult<&str, Vec<&str>> {
+///   separated_list(tag("|"), tag("abc"))(s)
+/// }
 ///
 /// assert_eq!(parser("abc|abc|abc"), Ok(("", vec!["abc", "abc", "abc"])));
 /// assert_eq!(parser("abc123abc"), Ok(("123abc", vec!["abc"])));
 /// assert_eq!(parser("abc|def"), Ok(("|def", vec!["abc"])));
 /// assert_eq!(parser(""), Ok(("", vec![])));
 /// assert_eq!(parser("def|abc"), Ok(("def|abc", vec![])));
-/// # }
 /// ```
-//FIXME: streaming
 #[cfg(feature = "alloc")]
 pub fn separated_list<I, O, O2, E, F, G>(sep: G, f: F) -> impl Fn(I) -> IResult<I, Vec<O>, E>
 where
@@ -327,28 +294,20 @@ where
 /// * `sep` Parses the separator between list elements.
 /// ```rust
 /// # #[macro_use] extern crate nom;
-/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
 /// use nom::multi::separated_nonempty_list;
 /// use nom::bytes::complete::tag;
-/// # fn main() {
-/// let separator_parser = |s: &'static str| {
-///   tag::<_, _, (_, ErrorKind)>("|")(s)
-/// };
-/// let embedded_parser = |s: &'static str| {
-///   tag::<_, _, (_, ErrorKind)>("abc")(s)
-/// };
-/// let parser = |s: &'static str| {
-///   separated_nonempty_list::<_, _, _, (_, ErrorKind), _, _>(separator_parser, embedded_parser)(s)
-/// };
+///
+/// fn parser(s: &str) -> IResult<&str, Vec<&str>> {
+///   separated_nonempty_list(tag("|"), tag("abc"))(s)
+/// }
 ///
 /// assert_eq!(parser("abc|abc|abc"), Ok(("", vec!["abc", "abc", "abc"])));
 /// assert_eq!(parser("abc123abc"), Ok(("123abc", vec!["abc"])));
 /// assert_eq!(parser("abc|def"), Ok(("|def", vec!["abc"])));
 /// assert_eq!(parser(""), Err(Err::Error(("", ErrorKind::Tag))));
 /// assert_eq!(parser("def|abc"), Err(Err::Error(("def|abc", ErrorKind::Tag))));
-/// # }
 /// ```
-//FIXME: streaming
 #[cfg(feature = "alloc")]
 pub fn separated_nonempty_list<I, O, O2, E, F, G>(sep: G, f: F) -> impl Fn(I) -> IResult<I, Vec<O>, E>
 where
@@ -401,7 +360,6 @@ where
   }
 }
 
-//FIXME: streaming
 // this implementation is used for type inference issues in macros
 #[doc(hidden)]
 #[cfg(feature = "alloc")]
@@ -424,25 +382,20 @@ where
 /// * `f` The parser to apply.
 /// ```rust
 /// # #[macro_use] extern crate nom;
-/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
 /// use nom::multi::many_m_n;
 /// use nom::bytes::complete::tag;
-/// # fn main() {
-/// let embedded_parser = |s: &'static str| {
-///   tag::<_, _, (_, ErrorKind)>("abc")(s)
-/// };
-/// let parser = |s: &'static str| {
-///   many_m_n::<_, _, (_, ErrorKind), _>(0, 2, embedded_parser)(s)
-/// };
+///
+/// fn parser(s: &str) -> IResult<&str, Vec<&str>> {
+///   many_m_n(0, 2, tag("abc"))(s)
+/// }
 ///
 /// assert_eq!(parser("abcabc"), Ok(("", vec!["abc", "abc"])));
 /// assert_eq!(parser("abc123"), Ok(("123", vec!["abc"])));
 /// assert_eq!(parser("123123"), Ok(("123123", vec![])));
 /// assert_eq!(parser(""), Ok(("", vec![])));
 /// assert_eq!(parser("abcabcabc"), Ok(("abc", vec!["abc", "abc"])));
-/// # }
 /// ```
-//FIXME: streaming
 #[cfg(feature = "alloc")]
 pub fn many_m_n<I, O, E, F>(m: usize, n: usize, f: F) -> impl Fn(I) -> IResult<I, Vec<O>, E>
 where
@@ -487,7 +440,6 @@ where
   }
 }
 
-//FIXME: streaming
 // this implementation is used for type inference issues in macros
 #[doc(hidden)]
 #[cfg(feature = "alloc")]
@@ -506,24 +458,19 @@ where
 /// * `f` The parser to apply.
 /// ```rust
 /// # #[macro_use] extern crate nom;
-/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
 /// use nom::multi::many0_count;
 /// use nom::bytes::complete::tag;
-/// # fn main() {
-/// let embedded_parser = |s: &'static str| {
-///   tag::<_, _, (_, ErrorKind)>("abc")(s)
-/// };
-/// let parser = |s: &'static str| {
-///   many0_count::<_, _, (_, ErrorKind), _>(embedded_parser)(s)
-/// };
+///
+/// fn parser(s: &str) -> IResult<&str, usize> {
+///   many0_count(tag("abc"))(s)
+/// }
 ///
 /// assert_eq!(parser("abcabc"), Ok(("", 2)));
 /// assert_eq!(parser("abc123"), Ok(("123", 1)));
 /// assert_eq!(parser("123123"), Ok(("123123", 0)));
 /// assert_eq!(parser(""), Ok(("", 0)));
-/// # }
 /// ```
-//FIXME: streaming
 pub fn many0_count<I, O, E, F>(f: F) -> impl Fn(I) -> IResult<I, usize, E>
 where
   I: Clone + PartialEq,
@@ -573,24 +520,19 @@ where
 /// * `f` The parser to apply.
 /// ```rust
 /// # #[macro_use] extern crate nom;
-/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
 /// use nom::multi::many1_count;
 /// use nom::bytes::complete::tag;
-/// # fn main() {
-/// let embedded_parser = |s: &'static str| {
-///   tag::<_, _, (_, ErrorKind)>("abc")(s)
-/// };
-/// let parser = |s: &'static str| {
-///   many1_count::<_, _, (_, ErrorKind), _>(embedded_parser)(s)
-/// };
+///
+/// fn parser(s: &str) -> IResult<&str, usize> {
+///   many1_count(tag("abc"))(s)
+/// }
 ///
 /// assert_eq!(parser("abcabc"), Ok(("", 2)));
 /// assert_eq!(parser("abc123"), Ok(("123", 1)));
 /// assert_eq!(parser("123123"), Err(Err::Error(("123123", ErrorKind::Many1Count))));
 /// assert_eq!(parser(""), Err(Err::Error(("", ErrorKind::Many1Count))));
-/// # }
 /// ```
-//FIXME: streaming
 pub fn many1_count<I, O, E, F>(f: F) -> impl Fn(I) -> IResult<I, usize, E>
 where
   I: Clone + PartialEq,
@@ -643,23 +585,19 @@ where
 /// * `count` How often to apply the parser.
 /// ```rust
 /// # #[macro_use] extern crate nom;
-/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
 /// use nom::multi::count;
 /// use nom::bytes::complete::tag;
-/// # fn main() {
-/// let embedded_parser = |s: &'static str| {
-///   tag::<_, _, (_, ErrorKind)>("abc")(s)
-/// };
-/// let parser = |s: &'static str| {
-///   count::<_, _, (_, ErrorKind), _>(embedded_parser, 2)(s)
-/// };
+///
+/// fn parser(s: &str) -> IResult<&str, Vec<&str>> {
+///   count(tag("abc"), 2)(s)
+/// }
 ///
 /// assert_eq!(parser("abcabc"), Ok(("", vec!["abc", "abc"])));
 /// assert_eq!(parser("abc123"), Err(Err::Error(("123", ErrorKind::Tag))));
 /// assert_eq!(parser("123123"), Err(Err::Error(("123123", ErrorKind::Tag))));
 /// assert_eq!(parser(""), Err(Err::Error(("", ErrorKind::Tag))));
 /// assert_eq!(parser("abcabcabc"), Ok(("abc", vec!["abc", "abc"])));
-/// # }
 /// ```
 #[cfg(feature = "alloc")]
 pub fn count<I, O, E, F>(f: F, count: usize) -> impl Fn(I) -> IResult<I, Vec<O>, E>
@@ -701,28 +639,26 @@ where
 ///       the current accumulator.
 /// ```rust
 /// # #[macro_use] extern crate nom;
-/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
 /// use nom::multi::fold_many0;
 /// use nom::bytes::complete::tag;
-/// # fn main() {
-/// let combiner = |mut acc: Vec<_>, item| {
-///     acc.push(item);
-///     acc
-/// };
-/// let embedded_parser = |s: &'static str| {
-///   tag::<_, _, (_, ErrorKind)>("abc")(s)
-/// };
-/// let parser = |s: &'static str| {
-///   fold_many0::<_, _, (_, ErrorKind), _, _, _>(embedded_parser, Vec::new(), combiner)(s)
-/// };
+///
+/// fn parser(s: &str) -> IResult<&str, Vec<&str>> {
+///   fold_many0(
+///     tag("abc"),
+///     Vec::new(),
+///     |mut acc: Vec<_>, item| {
+///       acc.push(item);
+///       acc
+///     }
+///   )(s)
+/// }
 ///
 /// assert_eq!(parser("abcabc"), Ok(("", vec!["abc", "abc"])));
 /// assert_eq!(parser("abc123"), Ok(("123", vec!["abc"])));
 /// assert_eq!(parser("123123"), Ok(("123123", vec![])));
 /// assert_eq!(parser(""), Ok(("", vec![])));
-/// # }
 /// ```
-//FIXME: streaming
 pub fn fold_many0<I, O, E, F, G, R>(f: F, init: R, g: G) -> impl Fn(I) -> IResult<I, R, E>
 where
   I: Clone + PartialEq,
@@ -781,28 +717,26 @@ where
 ///       the current accumulator.
 /// ```rust
 /// # #[macro_use] extern crate nom;
-/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
 /// use nom::multi::fold_many1;
 /// use nom::bytes::complete::tag;
-/// # fn main() {
-/// let combiner = |mut acc: Vec<_>, item| {
-///     acc.push(item);
-///     acc
-/// };
-/// let embedded_parser = |s: &'static str| {
-///   tag::<_, _, (_, ErrorKind)>("abc")(s)
-/// };
-/// let parser = |s: &'static str| {
-///   fold_many1::<_, _, (_, ErrorKind), _, _, _>(embedded_parser, Vec::new(), combiner)(s)
-/// };
+///
+/// fn parser(s: &str) -> IResult<&str, Vec<&str>> {
+///   fold_many1(
+///     tag("abc"),
+///     Vec::new(),
+///     |mut acc: Vec<_>, item| {
+///       acc.push(item);
+///       acc
+///     }
+///   )(s)
+/// }
 ///
 /// assert_eq!(parser("abcabc"), Ok(("", vec!["abc", "abc"])));
 /// assert_eq!(parser("abc123"), Ok(("123", vec!["abc"])));
 /// assert_eq!(parser("123123"), Err(Err::Error(("123123", ErrorKind::Many1))));
 /// assert_eq!(parser(""), Err(Err::Error(("", ErrorKind::Many1))));
-/// # }
 /// ```
-//FIXME: streaming
 pub fn fold_many1<I, O, E, F, G, R>(f: F, init: R, g: G) -> impl Fn(I) -> IResult<I, R, E>
 where
   I: Clone + PartialEq,
@@ -870,29 +804,29 @@ where
 ///       the current accumulator.
 /// ```rust
 /// # #[macro_use] extern crate nom;
-/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
 /// use nom::multi::fold_many_m_n;
 /// use nom::bytes::complete::tag;
-/// # fn main() {
-/// let combiner = |mut acc: Vec<_>, item| {
-///     acc.push(item);
-///     acc
-/// };
-/// let embedded_parser = |s: &'static str| {
-///   tag::<_, _, (_, ErrorKind)>("abc")(s)
-/// };
-/// let parser = |s: &'static str| {
-///   fold_many_m_n::<_, _, (_, ErrorKind), _, _, _>(0, 2, embedded_parser, Vec::new(), combiner)(s)
-/// };
+///
+/// fn parser(s: &str) -> IResult<&str, Vec<&str>> {
+///   fold_many_m_n(
+///     0,
+///     2,
+///     tag("abc"),
+///     Vec::new(),
+///     |mut acc: Vec<_>, item| {
+///       acc.push(item);
+///       acc
+///     }
+///   )(s)
+/// }
 ///
 /// assert_eq!(parser("abcabc"), Ok(("", vec!["abc", "abc"])));
 /// assert_eq!(parser("abc123"), Ok(("123", vec!["abc"])));
 /// assert_eq!(parser("123123"), Ok(("123123", vec![])));
 /// assert_eq!(parser(""), Ok(("", vec![])));
 /// assert_eq!(parser("abcabcabc"), Ok(("abc", vec!["abc", "abc"])));
-/// # }
 /// ```
-//FIXME: streaming
 pub fn fold_many_m_n<I, O, E, F, G, R>(m: usize, n: usize, f: F, init: R, g: G) -> impl Fn(I) ->IResult<I, R, E>
 where
   I: Clone + PartialEq,
@@ -951,26 +885,19 @@ where
 /// * `f` The parser to apply.
 /// ```rust
 /// # #[macro_use] extern crate nom;
-/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::{Err, error::ErrorKind, Needed, IResult};
 /// # use nom::Needed::Size;
 /// use nom::number::complete::be_u16;
 /// use nom::multi::length_value;
 /// use nom::bytes::complete::tag;
-/// # fn main() {
-/// let first_parser = |s: &'static [u8]| {
-///   be_u16(s)
-/// };
-/// let second_parser = |s: &'static [u8]| {
-///   tag::<_, _, (_, ErrorKind)>("abc")(s)
-/// };
-/// let parser = |s: &'static [u8]| {
-///   length_value::<_, _, _, (_, ErrorKind), _, _>(first_parser, second_parser)(s)
-/// };
+///
+/// fn parser(s: &[u8]) -> IResult<&[u8], &[u8]> {
+///   length_value(be_u16, tag("abc"))(s)
+/// }
 ///
 /// assert_eq!(parser(b"\x00\x03abcefg"), Ok((&b"efg"[..], &b"abc"[..])));
 /// assert_eq!(parser(b"\x00\x03123123"), Err(Err::Error((&b"123"[..], ErrorKind::Tag))));
 /// assert_eq!(parser(b"\x00\x03"), Err(Err::Incomplete(Size(3))));
-/// # }
 /// ```
 pub fn length_value<I, O, N, E, F, G>(f: F, g: G) -> impl Fn(I) -> IResult<I, O, E>
 where
diff --git a/src/number/complete.rs b/src/number/complete.rs
index 840f569..930e5ae 100644
--- a/src/number/complete.rs
+++ b/src/number/complete.rs
@@ -11,6 +11,18 @@ use character::complete::digit1;
 /// Recognizes an unsigned 1 byte integer (equivalent to take!(1))
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::be_u8;
+///
+/// let parser = |s| {
+///   be_u8(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x03abcefg"), Ok((&b"\x03abcefg"[..], 0x00)));
+/// assert_eq!(parser(b""), Err(Err::Error((&[][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn be_u8<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u8, E> {
   if i.len() < 1 {
@@ -23,7 +35,18 @@ pub fn be_u8<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u8, E>
 /// Recognizes big endian unsigned 2 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
-
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::be_u16;
+///
+/// let parser = |s| {
+///   be_u16(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x03abcefg"), Ok((&b"abcefg"[..], 0x0003)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn be_u16<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u16, E> {
   if i.len() < 2 {
@@ -37,6 +60,18 @@ pub fn be_u16<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u16, E
 /// Recognizes big endian unsigned 3 byte integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::be_u24;
+///
+/// let parser = |s| {
+///   be_u24(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x03\x05abcefg"), Ok((&b"abcefg"[..], 0x000305)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn be_u24<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u32, E> {
   if i.len() < 3 {
@@ -50,6 +85,18 @@ pub fn be_u24<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u32, E
 /// Recognizes big endian unsigned 4 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::be_u32;
+///
+/// let parser = |s| {
+///   be_u32(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x03\x05\x07abcefg"), Ok((&b"abcefg"[..], 0x00030507)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn be_u32<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u32, E> {
   if i.len() < 4 {
@@ -63,6 +110,18 @@ pub fn be_u32<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u32, E
 /// Recognizes big endian unsigned 8 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::be_u64;
+///
+/// let parser = |s| {
+///   be_u64(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x01\x02\x03\x04\x05\x06\x07abcefg"), Ok((&b"abcefg"[..], 0x0001020304050607)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn be_u64<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u64, E> {
   if i.len() < 8 {
@@ -77,6 +136,18 @@ pub fn be_u64<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u64, E
 /// Recognizes big endian unsigned 16 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::be_u128;
+///
+/// let parser = |s| {
+///   be_u128(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x01\x02\x03\x04\x05\x06\x07\x00\x01\x02\x03\x04\x05\x06\x07abcefg"), Ok((&b"abcefg"[..], 0x00010203040506070001020304050607)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 #[cfg(stable_i128)]
 pub fn be_u128<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u128, E> {
@@ -106,6 +177,18 @@ pub fn be_u128<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u128,
 /// Recognizes a signed 1 byte integer (equivalent to take!(1)
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::be_i8;
+///
+/// let parser = |s| {
+///   be_i8(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x03abcefg"), Ok((&b"\x03abcefg"[..], 0x00)));
+/// assert_eq!(parser(b""), Err(Err::Error((&[][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn be_i8<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i8, E> {
   map!(i, be_u8, |x| x as i8)
@@ -114,6 +197,18 @@ pub fn be_i8<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i8, E>
 /// Recognizes big endian signed 2 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::be_i16;
+///
+/// let parser = |s| {
+///   be_i16(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x03abcefg"), Ok((&b"abcefg"[..], 0x0003)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn be_i16<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i16, E> {
   map!(i, be_u16, |x| x as i16)
@@ -122,6 +217,18 @@ pub fn be_i16<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i16,
 /// Recognizes big endian signed 3 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::be_i24;
+///
+/// let parser = |s| {
+///   be_i24(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x03\x05abcefg"), Ok((&b"abcefg"[..], 0x000305)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn be_i24<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i32, E> {
   // Same as the unsigned version but we need to sign-extend manually here
@@ -135,6 +242,18 @@ pub fn be_i24<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i32, E
 /// Recognizes big endian signed 4 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::be_i32;
+///
+/// let parser = |s| {
+///   be_i32(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x03\x05\x07abcefg"), Ok((&b"abcefg"[..], 0x00030507)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn be_i32<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i32, E> {
   map!(i, be_u32, |x| x as i32)
@@ -143,6 +262,18 @@ pub fn be_i32<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i32, E
 /// Recognizes big endian signed 8 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::be_i64;
+///
+/// let parser = |s| {
+///   be_i64(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x01\x02\x03\x04\x05\x06\x07abcefg"), Ok((&b"abcefg"[..], 0x0001020304050607)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn be_i64<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i64, E> {
   map!(i, be_u64, |x| x as i64)
@@ -151,6 +282,18 @@ pub fn be_i64<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i64, E
 /// Recognizes big endian signed 16 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::be_i128;
+///
+/// let parser = |s| {
+///   be_i128(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x01\x02\x03\x04\x05\x06\x07\x00\x01\x02\x03\x04\x05\x06\x07abcefg"), Ok((&b"abcefg"[..], 0x00010203040506070001020304050607)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 #[cfg(stable_i128)]
 pub fn be_i128<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i128, E> {
@@ -160,6 +303,18 @@ pub fn be_i128<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i128
 /// Recognizes an unsigned 1 byte integer (equivalent to take!(1))
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::le_u8;
+///
+/// let parser = |s| {
+///   le_u8(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x03abcefg"), Ok((&b"\x03abcefg"[..], 0x00)));
+/// assert_eq!(parser(b""), Err(Err::Error((&[][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn le_u8<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u8, E> {
   if i.len() < 1 {
@@ -172,6 +327,18 @@ pub fn le_u8<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u8, E>
 /// Recognizes little endian unsigned 2 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::le_u16;
+///
+/// let parser = |s| {
+///   le_u16(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x03abcefg"), Ok((&b"abcefg"[..], 0x0300)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn le_u16<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u16, E> {
   if i.len() < 2 {
@@ -185,6 +352,18 @@ pub fn le_u16<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u16,
 /// Recognizes little endian unsigned 3 byte integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::le_u24;
+///
+/// let parser = |s| {
+///   le_u24(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x03\x05abcefg"), Ok((&b"abcefg"[..], 0x050300)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn le_u24<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u32, E> {
   if i.len() < 3 {
@@ -198,6 +377,18 @@ pub fn le_u24<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u32,
 /// Recognizes little endian unsigned 4 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::le_u32;
+///
+/// let parser = |s| {
+///   le_u32(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x03\x05\x07abcefg"), Ok((&b"abcefg"[..], 0x07050300)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn le_u32<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u32, E> {
   if i.len() < 4 {
@@ -211,6 +402,18 @@ pub fn le_u32<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u32,
 /// Recognizes little endian unsigned 8 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::le_u64;
+///
+/// let parser = |s| {
+///   le_u64(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x01\x02\x03\x04\x05\x06\x07abcefg"), Ok((&b"abcefg"[..], 0x0706050403020100)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn le_u64<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u64, E> {
   if i.len() < 8 {
@@ -225,6 +428,18 @@ pub fn le_u64<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u64,
 /// Recognizes little endian unsigned 16 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::le_u128;
+///
+/// let parser = |s| {
+///   le_u128(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x01\x02\x03\x04\x05\x06\x07\x00\x01\x02\x03\x04\x05\x06\x07abcefg"), Ok((&b"abcefg"[..], 0x07060504030201000706050403020100)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 #[cfg(stable_i128)]
 pub fn le_u128<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u128, E> {
@@ -254,6 +469,18 @@ pub fn le_u128<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u128
 /// Recognizes a signed 1 byte integer (equivalent to take!(1))
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::le_i8;
+///
+/// let parser = |s| {
+///   le_i8(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x03abcefg"), Ok((&b"\x03abcefg"[..], 0x00)));
+/// assert_eq!(parser(b""), Err(Err::Error((&[][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn le_i8<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i8, E> {
   map!(i, le_u8, |x| x as i8)
@@ -262,6 +489,18 @@ pub fn le_i8<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i8, E>
 /// Recognizes little endian signed 2 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::le_i16;
+///
+/// let parser = |s| {
+///   le_i16(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x03abcefg"), Ok((&b"abcefg"[..], 0x0300)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn le_i16<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i16, E> {
   map!(i, le_u16, |x| x as i16)
@@ -270,6 +509,18 @@ pub fn le_i16<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i16,
 /// Recognizes little endian signed 3 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::le_i24;
+///
+/// let parser = |s| {
+///   le_i24(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x03\x05abcefg"), Ok((&b"abcefg"[..], 0x050300)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn le_i24<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i32, E> {
   // Same as the unsigned version but we need to sign-extend manually here
@@ -283,6 +534,18 @@ pub fn le_i24<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i32,
 /// Recognizes little endian signed 4 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::le_i32;
+///
+/// let parser = |s| {
+///   le_i32(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x03\x05\x07abcefg"), Ok((&b"abcefg"[..], 0x07050300)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn le_i32<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i32, E> {
   map!(i, le_u32, |x| x as i32)
@@ -291,6 +554,18 @@ pub fn le_i32<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i32,
 /// Recognizes little endian signed 8 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::le_i64;
+///
+/// let parser = |s| {
+///   le_i64(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x01\x02\x03\x04\x05\x06\x07abcefg"), Ok((&b"abcefg"[..], 0x0706050403020100)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn le_i64<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i64, E> {
   map!(i, le_u64, |x| x as i64)
@@ -299,6 +574,18 @@ pub fn le_i64<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i64,
 /// Recognizes little endian signed 16 bytes integer
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::le_i128;
+///
+/// let parser = |s| {
+///   le_i128(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x01\x02\x03\x04\x05\x06\x07\x00\x01\x02\x03\x04\x05\x06\x07abcefg"), Ok((&b"abcefg"[..], 0x07060504030201000706050403020100)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Error((&[0x01][..], ErrorKind::Eof))));
+/// ```
 #[inline]
 #[cfg(stable_i128)]
 pub fn le_i128<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i128, E> {
@@ -308,6 +595,18 @@ pub fn le_i128<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i128
 /// Recognizes big endian 4 bytes floating point number
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::be_f32;
+///
+/// let parser = |s| {
+///   be_f32(s)
+/// };
+///
+/// assert_eq!(parser(&[0x41, 0x48, 0x00, 0x00][..]), Ok((&b""[..], 12.5)));
+/// assert_eq!(parser(b"abc"), Err(Err::Error((&b"abc"[..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn be_f32<'a, E: ParseError<&'a [u8]>>(input: &'a[u8]) -> IResult<&'a[u8], f32, E> {
   match be_u32(input) {
@@ -319,6 +618,18 @@ pub fn be_f32<'a, E: ParseError<&'a [u8]>>(input: &'a[u8]) -> IResult<&'a[u8], f
 /// Recognizes big endian 8 bytes floating point number
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::be_f64;
+///
+/// let parser = |s| {
+///   be_f64(s)
+/// };
+///
+/// assert_eq!(parser(&[0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00][..]), Ok((&b""[..], 12.5)));
+/// assert_eq!(parser(b"abc"), Err(Err::Error((&b"abc"[..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn be_f64<'a, E: ParseError<&'a [u8]>>(input: &'a[u8]) -> IResult<&'a[u8], f64, E> {
   match be_u64(input) {
@@ -330,6 +641,18 @@ pub fn be_f64<'a, E: ParseError<&'a [u8]>>(input: &'a[u8]) -> IResult<&'a[u8], f
 /// Recognizes little endian 4 bytes floating point number
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::le_f32;
+///
+/// let parser = |s| {
+///   le_f32(s)
+/// };
+///
+/// assert_eq!(parser(&[0x00, 0x00, 0x48, 0x41][..]), Ok((&b""[..], 12.5)));
+/// assert_eq!(parser(b"abc"), Err(Err::Error((&b"abc"[..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn le_f32<'a, E: ParseError<&'a [u8]>>(input: &'a[u8]) -> IResult<&'a[u8], f32, E> {
   match le_u32(input) {
@@ -341,6 +664,18 @@ pub fn le_f32<'a, E: ParseError<&'a [u8]>>(input: &'a[u8]) -> IResult<&'a[u8], f
 /// Recognizes little endian 8 bytes floating point number
 ///
 /// *complete version*: returns an error if there is not enough input data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::le_f64;
+///
+/// let parser = |s| {
+///   le_f64(s)
+/// };
+///
+/// assert_eq!(parser(&[0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40][..]), Ok((&b""[..], 12.5)));
+/// assert_eq!(parser(b"abc"), Err(Err::Error((&b"abc"[..], ErrorKind::Eof))));
+/// ```
 #[inline]
 pub fn le_f64<'a, E: ParseError<&'a [u8]>>(input: &'a[u8]) -> IResult<&'a[u8], f64, E> {
   match le_u64(input) {
@@ -352,6 +687,19 @@ pub fn le_f64<'a, E: ParseError<&'a [u8]>>(input: &'a[u8]) -> IResult<&'a[u8], f
 /// Recognizes a hex-encoded integer
 ///
 /// *complete version*: will parse until the end of input if it has less than 8 bytes
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::hex_u32;
+///
+/// let parser = |s| {
+///   hex_u32(s)
+/// };
+///
+/// assert_eq!(parser(b"01AE"), Ok((&b""[..], 0x01AE)));
+/// assert_eq!(parser(b"abc"), Ok((&b""[..], 0x0ABC)));
+/// assert_eq!(parser(b"ggg"), Err(Err::Error((&b"ggg"[..], ErrorKind::IsA))));
+/// ```
 #[inline]
 pub fn hex_u32<'a, E: ParseError<&'a [u8]>>(input: &'a[u8]) -> IResult<&'a[u8], u32, E> {
   let (i, o) = ::bytes::complete::is_a(&b"0123456789abcdefABCDEF"[..])(input)?;
@@ -375,9 +723,24 @@ pub fn hex_u32<'a, E: ParseError<&'a [u8]>>(input: &'a[u8]) -> IResult<&'a[u8],
   Ok((remaining, res))
 }
 
-/// Recognizes floating point number in a byte string and returns a f32
+/// Recognizes floating point number in a byte string and returns the corresponding slice
 ///
 /// *complete version*: can parse until the end of input
+///
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::recognize_float;
+///
+/// let parser = |s| {
+///   recognize_float(s)
+/// };
+///
+/// assert_eq!(parser("11e-1"), Ok(("", "11e-1")));
+/// assert_eq!(parser("123E-02"), Ok(("", "123E-02")));
+/// assert_eq!(parser("123K-01"), Ok(("K-01", "123")));
+/// assert_eq!(parser("abc"), Err(Err::Error(("abc", ErrorKind::Alt))));
+/// ```
 #[allow(unused_imports)]
 #[cfg_attr(rustfmt, rustfmt_skip)]
 pub fn recognize_float<T, E:ParseError<T>>(input: T) -> IResult<T, T, E>
@@ -411,6 +774,20 @@ where
 /// Recognizes floating point number in a byte string and returns a f32
 ///
 /// *complete version*: can parse until the end of input
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::float;
+///
+/// let parser = |s| {
+///   float::<_, (_, ErrorKind)>(s)
+/// };
+///
+/// assert_eq!(parser("11e-1"), Ok(("", 1.1)));
+/// assert_eq!(parser("123E-02"), Ok(("", 1.23)));
+/// assert_eq!(parser("123K-01"), Ok(("K-01", 123.0)));
+/// assert_eq!(parser("abc"), Err(Err::Error(("abc", ErrorKind::Alt))));
+/// ```
 #[cfg(not(feature = "lexical"))]
 pub fn float<T, E:ParseError<T>>(input: T) -> IResult<T, f32, E>
 where
@@ -436,6 +813,20 @@ where
 ///
 /// this function uses the lexical-core crate for float parsing by default, you
 /// can deactivate it by removing the "lexical" feature
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::float;
+///
+/// let parser = |s| {
+///   float::<_, (_, ErrorKind)>(s)
+/// };
+///
+/// assert_eq!(parser("1.1"), Ok(("", 1.1)));
+/// assert_eq!(parser("123E-02"), Ok(("", 1.23)));
+/// assert_eq!(parser("123K-01"), Ok(("K-01", 123.0)));
+/// assert_eq!(parser("abc"), Ok(("abc", 0.0)));
+/// ```
 #[cfg(feature = "lexical")]
 pub fn float<T, E:ParseError<T>>(input: T) -> IResult<T, f32, E>
 where
@@ -453,6 +844,20 @@ where
 /// Recognizes floating point number in a byte string and returns a f64
 ///
 /// *complete version*: can parse until the end of input
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::double;
+///
+/// let parser = |s| {
+///   double::<_, (_, ErrorKind)>(s)
+/// };
+///
+/// assert_eq!(parser("11e-1"), Ok(("", 1.1)));
+/// assert_eq!(parser("123E-02"), Ok(("", 1.23)));
+/// assert_eq!(parser("123K-01"), Ok(("K-01", 123.0)));
+/// assert_eq!(parser("abc"), Err(Err::Error(("abc", ErrorKind::Alt))));
+/// ```
 #[cfg(not(feature = "lexical"))]
 pub fn double<T, E:ParseError<T>>(input: T) -> IResult<T, f64, E>
 where
@@ -478,6 +883,20 @@ where
 ///
 /// this function uses the lexical-core crate for float parsing by default, you
 /// can deactivate it by removing the "lexical" feature
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::complete::double;
+///
+/// let parser = |s| {
+///   double::<_, (_, ErrorKind)>(s)
+/// };
+///
+/// assert_eq!(parser("1.1"), Ok(("", 1.1)));
+/// assert_eq!(parser("123E-02"), Ok(("", 1.23)));
+/// assert_eq!(parser("123K-01"), Ok(("K-01", 123.0)));
+/// assert_eq!(parser("abc"), Ok(("abc", 0.0)));
+/// ```
 #[cfg(feature = "lexical")]
 pub fn double<T, E:ParseError<T>>(input: T) -> IResult<T, f64, E>
 where
diff --git a/src/number/streaming.rs b/src/number/streaming.rs
index 3c0ebdc..95885b8 100644
--- a/src/number/streaming.rs
+++ b/src/number/streaming.rs
@@ -9,7 +9,20 @@ use character::streaming::digit1;
 
 /// Recognizes an unsigned 1 byte integer (equivalent to take!(1))
 ///
-/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enoughdata
+/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::streaming::be_u8;
+///
+/// /*let parser = |s| {
+///   be_u8::<(_, ErrorKind)>(s)
+/// };*/
+/// let parser = be_u8::<(_, ErrorKind)>;
+///
+/// assert_eq!(parser(b"\x00\x01abcd"), Ok((&b"\x01abcd"[..], 0x00)));
+/// assert_eq!(parser(b""), Err(Err::Incomplete(Needed::Size(1))));
+/// ```
 #[inline]
 pub fn be_u8<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u8, E> {
   if i.len() < 1 {
@@ -22,6 +35,19 @@ pub fn be_u8<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u8, E>
 /// Recognizes big endian unsigned 2 bytes integer
 ///
 /// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
+///
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::streaming::be_u16;
+///
+/// let parser = |s| {
+///   be_u16::<(_, ErrorKind)>(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x01abcd"), Ok((&b"abcd"[..], 0x0001)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Incomplete(Needed::Size(2))));
+/// ```
 #[inline]
 pub fn be_u16<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u16, E> {
   if i.len() < 2 {
@@ -35,6 +61,19 @@ pub fn be_u16<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u16, E
 /// Recognizes big endian unsigned 3 byte integer
 ///
 /// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
+///
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::streaming::be_u24;
+///
+/// let parser = |s| {
+///   be_u24::<(_, ErrorKind)>(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x01\x02abcd"), Ok((&b"abcd"[..], 0x000102)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Incomplete(Needed::Size(3))));
+/// ```
 #[inline]
 pub fn be_u24<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u32, E> {
   if i.len() < 3 {
@@ -48,6 +87,19 @@ pub fn be_u24<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u32, E
 /// Recognizes big endian unsigned 4 bytes integer
 ///
 /// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
+///
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::streaming::be_u32;
+///
+/// let parser = |s| {
+///   be_u32::<(_, ErrorKind)>(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x01\x02\x03abcd"), Ok((&b"abcd"[..], 0x00010203)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Incomplete(Needed::Size(4))));
+/// ```
 #[inline]
 pub fn be_u32<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u32, E> {
   if i.len() < 4 {
@@ -61,6 +113,19 @@ pub fn be_u32<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u32, E
 /// Recognizes big endian unsigned 8 bytes integer
 ///
 /// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
+/// 
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::streaming::be_u64;
+///
+/// let parser = |s| {
+///   be_u64::<(_, ErrorKind)>(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x01\x02\x03\x04\x05\x06\x07abcd"), Ok((&b"abcd"[..], 0x0001020304050607)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Incomplete(Needed::Size(8))));
+/// ```
 #[inline]
 pub fn be_u64<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u64, E> {
   if i.len() < 8 {
@@ -72,9 +137,21 @@ pub fn be_u64<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u64, E
   }
 }
 
-/// Recognizes big endian unsigned 16 bytes integer
+/// Recognizes a big endian unsigned 16 bytes integer
 ///
 /// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::streaming::be_u128;
+///
+/// let parser = |s| {
+///   be_u128::<(_, ErrorKind)>(s)
+/// };
+///
+/// assert_eq!(parser(b"\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15abcd"), Ok((&b"abcd"[..], 0x00010203040506070809101112131415)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Incomplete(Needed::Size(16))));
+/// ```
 #[inline]
 #[cfg(stable_i128)]
 pub fn be_u128<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u128, E> {
@@ -104,22 +181,52 @@ pub fn be_u128<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], u128,
 /// Recognizes a signed 1 byte integer (equivalent to take!(1))
 ///
 /// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::streaming::be_i8;
+///
+/// let parser = be_i8::<(_, ErrorKind)>;
+///
+/// assert_eq!(parser(b"\x00\x01abcd"), Ok((&b"\x01abcd"[..], 0x00)));
+/// assert_eq!(parser(b""), Err(Err::Incomplete(Needed::Size(1))));
+/// ```
 #[inline]
 pub fn be_i8<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i8, E> {
   map!(i, be_u8, |x| x as i8)
 }
 
-/// Recognizes big endian signed 2 bytes integer
+/// Recognizes a big endian signed 2 bytes integer
 ///
 /// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::streaming::be_i16;
+///
+/// let parser = be_i16::<(_, ErrorKind)>;
+///
+/// assert_eq!(parser(b"\x00\x01abcd"), Ok((&b"abcd"[..], 0x0001)));
+/// assert_eq!(parser(b""), Err(Err::Incomplete(Needed::Size(2))));
+/// ```
 #[inline]
 pub fn be_i16<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i16, E> {
   map!(i, be_u16, |x| x as i16)
 }
 
-/// Recognizes big endian signed 3 bytes integer
+/// Recognizes a big endian signed 3 bytes integer
 ///
 /// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::streaming::be_i24;
+///
+/// let parser = be_i24::<(_, ErrorKind)>;
+///
+/// assert_eq!(parser(b"\x00\x01\x02abcd"), Ok((&b"abcd"[..], 0x000102)));
+/// assert_eq!(parser(b""), Err(Err::Incomplete(Needed::Size(3))));
+/// ```
 #[inline]
 pub fn be_i24<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i32, E> {
   // Same as the unsigned version but we need to sign-extend manually here
@@ -130,9 +237,19 @@ pub fn be_i24<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i32, E
   })
 }
 
-/// Recognizes big endian signed 4 bytes integer
+/// Recognizes a big endian signed 4 bytes integer
 ///
 /// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::streaming::be_i32;
+///
+/// let parser = be_i32::<(_, ErrorKind)>;
+///
+/// assert_eq!(parser(b"\x00\x01\x02\x03abcd"), Ok((&b"abcd"[..], 0x00010203)));
+/// assert_eq!(parser(b""), Err(Err::Incomplete(Needed::Size(4))));
+/// ```
 #[inline]
 pub fn be_i32<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i32, E> {
   map!(i, be_u32, |x| x as i32)
@@ -141,14 +258,35 @@ pub fn be_i32<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i32, E
 /// Recognizes big endian signed 8 bytes integer
 ///
 /// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
+/// 
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::streaming::be_i64;
+///
+/// let parser = be_i64::<(_, ErrorKind)>;
+///
+/// assert_eq!(parser(b"\x00\x01\x02\x03\x04\x05\x06\x07abcd"), Ok((&b"abcd"[..], 0x0001020304050607)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Incomplete(Needed::Size(8))));
+/// ```
 #[inline]
 pub fn be_i64<'a, E: ParseError<&'a[u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i64, E> {
   map!(i, be_u64, |x| x as i64)
 }
 
-/// Recognizes big endian signed 16 bytes integer
+/// Recognizes a big endian signed 16 bytes integer
 ///
 /// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
+/// ```rust
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::number::streaming::be_i128;
+///
+/// let parser = be_i128::<(_, ErrorKind)>;
+///
+/// assert_eq!(parser(b"\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15abcd"), Ok((&b"abcd"[..], 0x00010203040506070809101112131415)));
+/// assert_eq!(parser(b"\x01"), Err(Err::Incomplete(Needed::Size(16))));
+/// ```
 #[inline]
 #[cfg(stable_i128)]
 pub fn be_i128<'a, E: ParseError<&'a [u8]>>(i: &'a[u8]) -> IResult<&'a[u8], i128, E> {
diff --git a/src/sequence/mod.rs b/src/sequence/mod.rs
index a8a4595..fb37c68 100644
--- a/src/sequence/mod.rs
+++ b/src/sequence/mod.rs
@@ -6,6 +6,34 @@ mod macros;
 use internal::IResult;
 use error::ParseError;
 
+/// Gets an object from the first parser,
+/// then gets another object from the second parser.
+/// # Arguments
+/// * `first` The first parser to apply.
+/// * `second` The second parser to apply.
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::sequence::pair;
+/// use nom::bytes::complete::tag;
+/// # fn main() {
+/// let first_parser = |s: &'static str| {
+///   tag::<_, _, (_, ErrorKind)>("abc")(s)
+/// };
+/// let second_parser = |s: &'static str| {
+///   tag::<_, _, (_, ErrorKind)>("efg")(s)
+/// };
+/// let parser = |s: &'static str| {
+///   pair::<_, _, _, (_, ErrorKind), _, _>(first_parser, second_parser)(s)
+/// };
+///
+/// assert_eq!(parser("abcefg"), Ok(("", ("abc", "efg"))));
+/// assert_eq!(parser("abcefghij"), Ok(("hij", ("abc", "efg"))));
+/// assert_eq!(parser(""), Err(Err::Error(("", ErrorKind::Tag))));
+/// assert_eq!(parser("123"), Err(Err::Error(("123", ErrorKind::Tag))));
+/// # }
+/// ```
 pub fn pair<I, O1, O2, E: ParseError<I>, F, G>(first: F, second: G) -> impl Fn(I) -> IResult<I, (O1, O2), E>
 where
   F: Fn(I) -> IResult<I, O1, E>,
@@ -27,6 +55,34 @@ where
   pair(first, second)(input)
 }
 
+/// Matches an object from the first parser and discards it,
+/// then gets an object from the second parser.
+/// # Arguments
+/// * `first` The opening parser.
+/// * `second` The second parser to get object.
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::sequence::preceded;
+/// use nom::bytes::complete::tag;
+/// # fn main() {
+/// let first_parser = |s: &'static str| {
+///   tag::<_, _, (_, ErrorKind)>("abc")(s)
+/// };
+/// let second_parser = |s: &'static str| {
+///   tag::<_, _, (_, ErrorKind)>("efg")(s)
+/// };
+/// let parser = |s: &'static str| {
+///   preceded::<_, _, _, (_, ErrorKind), _, _>(first_parser, second_parser)(s)
+/// };
+///
+/// assert_eq!(parser("abcefg"), Ok(("", "efg")));
+/// assert_eq!(parser("abcefghij"), Ok(("hij", "efg")));
+/// assert_eq!(parser(""), Err(Err::Error(("", ErrorKind::Tag))));
+/// assert_eq!(parser("123"), Err(Err::Error(("123", ErrorKind::Tag))));
+/// # }
+/// ```
 pub fn preceded<I, O1, O2, E: ParseError<I>, F, G>(first: F, second: G) -> impl Fn(I) -> IResult<I, O2, E>
 where
   F: Fn(I) -> IResult<I, O1, E>,
@@ -48,6 +104,34 @@ where
   preceded(first, second)(input)
 }
 
+/// Gets an object from the first parser,
+/// then matches an object from the second parser and discards it.
+/// # Arguments
+/// * `first` The first parser to apply.
+/// * `second` The second parser to match an object.
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::sequence::terminated;
+/// use nom::bytes::complete::tag;
+/// # fn main() {
+/// let first_parser = |s: &'static str| {
+///   tag::<_, _, (_, ErrorKind)>("abc")(s)
+/// };
+/// let second_parser = |s: &'static str| {
+///   tag::<_, _, (_, ErrorKind)>("efg")(s)
+/// };
+/// let parser = |s: &'static str| {
+///   terminated::<_, _, _, (_, ErrorKind), _, _>(first_parser, second_parser)(s)
+/// };
+///
+/// assert_eq!(parser("abcefg"), Ok(("", "abc")));
+/// assert_eq!(parser("abcefghij"), Ok(("hij", "abc")));
+/// assert_eq!(parser(""), Err(Err::Error(("", ErrorKind::Tag))));
+/// assert_eq!(parser("123"), Err(Err::Error(("123", ErrorKind::Tag))));
+/// # }
+/// ```
 pub fn terminated<I, O1, O2, E: ParseError<I>, F, G>(first: F, second: G) -> impl Fn(I) -> IResult<I, O1, E>
 where
   F: Fn(I) -> IResult<I, O1, E>,
@@ -69,6 +153,39 @@ where
   terminated(first, second)(input)
 }
 
+/// 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.
+/// # Arguments
+/// * `first` The first parser to apply.
+/// * `sep` The separator parser to apply.
+/// * `second` The second parser to apply.
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::sequence::separated_pair;
+/// use nom::bytes::complete::tag;
+/// # fn main() {
+/// let first_parser = |s: &'static str| {
+///   tag::<_, _, (_, ErrorKind)>("abc")(s)
+/// };
+/// let sep_parser = |s: &'static str| {
+///   tag::<_, _, (_, ErrorKind)>("|")(s)
+/// };
+/// let second_parser = |s: &'static str| {
+///   tag::<_, _, (_, ErrorKind)>("efg")(s)
+/// };
+/// let parser = |s: &'static str| {
+///   separated_pair::<_, _, _, _, (_, ErrorKind), _, _, _>(first_parser, sep_parser, second_parser)(s)
+/// };
+///
+/// assert_eq!(parser("abc|efg"), Ok(("", ("abc", "efg"))));
+/// assert_eq!(parser("abc|efghij"), Ok(("hij", ("abc", "efg"))));
+/// assert_eq!(parser(""), Err(Err::Error(("", ErrorKind::Tag))));
+/// assert_eq!(parser("123"), Err(Err::Error(("123", ErrorKind::Tag))));
+/// # }
+/// ```
 pub fn separated_pair<I, O1, O2, O3, E: ParseError<I>, F, G, H>(first: F, sep: G, second: H) -> impl Fn(I) -> IResult<I, (O1, O3), E>
 where
   F: Fn(I) -> IResult<I, O1, E>,
@@ -93,6 +210,39 @@ where
   separated_pair(first, sep, second)(input)
 }
 
+/// Matches an object from the first parser,
+/// then gets an object from the sep_parser,
+/// then matches another object from the second parser.
+/// # Arguments
+/// * `first` The first parser to apply.
+/// * `sep` The separator parser to apply.
+/// * `second` The second parser to apply.
+/// ```rust
+/// # #[macro_use] extern crate nom;
+/// # use nom::{Err, error::ErrorKind, Needed};
+/// # use nom::Needed::Size;
+/// use nom::sequence::delimited;
+/// use nom::bytes::complete::tag;
+/// # fn main() {
+/// let first_parser = |s: &'static str| {
+///   tag::<_, _, (_, ErrorKind)>("abc")(s)
+/// };
+/// let sep_parser = |s: &'static str| {
+///   tag::<_, _, (_, ErrorKind)>("|")(s)
+/// };
+/// let second_parser = |s: &'static str| {
+///   tag::<_, _, (_, ErrorKind)>("efg")(s)
+/// };
+/// let parser = |s: &'static str| {
+///   delimited::<_, _, _, _, (_, ErrorKind), _, _, _>(first_parser, sep_parser, second_parser)(s)
+/// };
+///
+/// assert_eq!(parser("abc|efg"), Ok(("", "|")));
+/// assert_eq!(parser("abc|efghij"), Ok(("hij", "|")));
+/// assert_eq!(parser(""), Err(Err::Error(("", ErrorKind::Tag))));
+/// assert_eq!(parser("123"), Err(Err::Error(("123", ErrorKind::Tag))));
+/// # }
+/// ```
 pub fn delimited<I, O1, O2, O3, E: ParseError<I>, F, G, H>(first: F, sep: G, second: H) -> impl Fn(I) -> IResult<I, O2, E>
 where
   F: Fn(I) -> IResult<I, O1, E>,
@@ -117,7 +267,11 @@ where
   delimited(first, sep, second)(input)
 }
 
+/// helper trait for the tuple combinator
+///
+/// this trait is implemented for tuples of parsers of up to 21 elements
 pub trait Tuple<I,O,E> {
+  /// parses the input and returns a tuple of results of each parser
   fn parse(&self, input: I) -> IResult<I,O,E>;
 }
 
@@ -171,6 +325,7 @@ macro_rules! tuple_trait_inner(
 tuple_trait!(FnA A, FnB B, FnC C, FnD D, FnE E, FnF F, FnG G, FnH H, FnI I, FnJ J, FnK K, FnL L,
   FnM M, FnN N, FnO O, FnP P, FnQ Q, FnR R, FnS S, FnT T, FnU U);
 
+/// applies a tuple of parsers one by one and returns their results as a tuple
 pub fn tuple<I: Clone, O, E: ParseError<I>, List: Tuple<I,O,E>>(l: List)  -> impl Fn(I) -> IResult<I, O, E> {
   move |i: I| {
     l.parse(i)
diff --git a/src/traits.rs b/src/traits.rs
index 8ff2fc7..7e980f5 100644
--- a/src/traits.rs
+++ b/src/traits.rs
@@ -90,8 +90,9 @@ impl<'a> Offset for &'a str {
   }
 }
 
-/// casts the input type to a byte slice
+/// Helper trait for types that can be viewed as a byte slice
 pub trait AsBytes {
+  /// casts the input type to a byte slice
   fn as_bytes(&self) -> &[u8];
 }
 
@@ -612,8 +613,11 @@ impl<'a> InputTakeAtPosition for &'a str {
 /// if more data was needed
 #[derive(Debug, PartialEq)]
 pub enum CompareResult {
+  /// comparison was successful
   Ok,
+  /// we need more data to be sure
   Incomplete,
+  /// comparison failed
   Error,
 }
 
@@ -715,7 +719,6 @@ impl<'a, 'b> Compare<&'b str> for &'a str {
   }
 
   //FIXME: this version is too simple and does not use the current locale
-  #[cfg(feature = "alloc")]
   #[inline(always)]
   fn compare_no_case(&self, t: &'b str) -> CompareResult {
     let pos = self
@@ -734,16 +737,11 @@ impl<'a, 'b> Compare<&'b str> for &'a str {
       }
     }
   }
-
-  #[cfg(not(feature = "alloc"))]
-  #[inline(always)]
-  fn compare_no_case(&self, _: &'b str) -> CompareResult {
-    unimplemented!()
-  }
 }
 
-/// look for self in the given input stream
+/// look for a token in self
 pub trait FindToken<T> {
+  /// returns true if self contains the token
   fn find_token(&self, token: T) -> bool;
 }
 
@@ -790,6 +788,7 @@ impl<'a> FindToken<char> for &'a str {
 
 /// look for a substring in self
 pub trait FindSubstring<T> {
+  /// returns the byte position of the substring if it is found
   fn find_substring(&self, substr: T) -> Option<usize>;
 }
 
@@ -845,6 +844,8 @@ impl<'a, 'b> FindSubstring<&'b str> for &'a str {
 
 /// used to integrate str's parse() method
 pub trait ParseTo<R> {
+  /// succeeds if `parse()` succeeded. The byte slice implementation
+  /// will first convert it to a &str, then apply the `parse()` function
   fn parse_to(&self) -> Option<R>;
 }
 
@@ -867,6 +868,7 @@ impl<'a, R: FromStr> ParseTo<R> for &'a str {
 /// something else than a `&[T]` or `&str`
 pub trait Slice<R> {
   #[inline(always)]
+  /// slices self according to the range argument
   fn slice(&self, range: R) -> Self;
 }
 
@@ -1061,7 +1063,14 @@ impl ExtendInto for char {
   }
 }
 
+/// Helper trait to convert numbers to usize
+///
+/// by default, usize implements `From<u8>` and `From<u16>` but not
+/// `From<u32>` and `From<u64>` because that would be invalid on some
+/// platforms. This trait implements the conversion for platforms
+/// with 32 and 64 bits pointer platforms
 pub trait ToUsize {
+  /// converts self to usize
   fn to_usize(&self) -> usize;
 }
 
diff --git a/src/util.rs b/src/util.rs
index 5adb43c..9c132ef 100644
--- a/src/util.rs
+++ b/src/util.rs
@@ -2,6 +2,7 @@
 use lib::std::vec::Vec;
 
 #[cfg(feature = "std")]
+/// Helper trait to show a byte slice as a hex dump
 pub trait HexDisplay {
   /// Converts the value of `self` to a hex dump, returning the owned
   /// string.
@@ -420,8 +421,3 @@ pub fn print_offsets<E>(input: &[u8], from: usize, offsets: &[(ErrorKind<E>, usi
   String::from_utf8_lossy(&v[..]).into_owned()
 }
   */
-
-pub trait Convert<T> {
-  fn convert(T) -> Self;
-}
-
diff --git a/src/whitespace.rs b/src/whitespace.rs
index c7bf083..91cc70e 100644
--- a/src/whitespace.rs
+++ b/src/whitespace.rs
@@ -44,7 +44,6 @@
 //! macro_rules! sp (
 //!   ($i:expr, $($args:tt)*) => (
 //!     {
-//!       use nom::Convert;
 //!       use nom::Err;
 //!
 //!       match sep!($i, space, $($args)*) {
@@ -99,7 +98,7 @@
 macro_rules! wrap_sep (
   ($i:expr, $separator:expr, $submac:ident!( $($args:tt)* )) => ({
     use $crate::lib::std::result::Result::*;
-    use $crate::{Err,Convert,IResult};
+    use $crate::{Err,IResult};
 
     fn unify_types<I,O,P,E>(_: &IResult<I,O,E>, _: &IResult<I,P,E>) {}
 
@@ -375,7 +374,7 @@ macro_rules! permutation_sep (
     {
       use $crate::lib::std::result::Result::*;
       use $crate::lib::std::option::Option::*;
-      use $crate::{Err,error::ErrorKind,Convert};
+      use $crate::{Err,error::ErrorKind};
 
       let mut res    = permutation_init!((), $($rest)*);
       let mut input  = $i;
@@ -859,7 +858,6 @@ macro_rules! sep (
 macro_rules! ws (
   ($i:expr, $($args:tt)*) => (
     {
-      use $crate::Convert;
       use $crate::Err;
       use $crate::lib::std::result::Result::*;
       use $crate::character::complete::multispace0;


Test patch:
diff --git a/tests/arithmetic.rs b/tests/arithmetic.rs
index 7ef3264..b3c3893 100644
--- a/tests/arithmetic.rs
+++ b/tests/arithmetic.rs
@@ -1,4 +1,3 @@
-#[macro_use]
 extern crate nom;
 
 
diff --git a/tests/arithmetic_ast.rs b/tests/arithmetic_ast.rs
index 1973edd..ecb8d40 100644
--- a/tests/arithmetic_ast.rs
+++ b/tests/arithmetic_ast.rs
@@ -1,4 +1,3 @@
-#[macro_use]
 extern crate nom;
 
 use std::fmt;
diff --git a/tests/ini_str.rs b/tests/ini_str.rs
index 8b8bded..d778918 100644
--- a/tests/ini_str.rs
+++ b/tests/ini_str.rs
@@ -3,7 +3,7 @@ extern crate nom;
 
 use nom::{
   IResult,
-  combinator::{map_res, opt},
+  combinator::opt,
   bytes::complete::{take_while, is_a},
   sequence::{delimited, terminated},
   character::complete::{char, alphanumeric1 as alphanumeric, space0 as space}
@@ -11,22 +11,6 @@ use nom::{
 
 use std::collections::HashMap;
 
-fn is_alphabetic(chr: char) -> bool {
-  (chr as u8 >= 0x41 && chr as u8 <= 0x5A) || (chr as u8 >= 0x61 && chr as u8 <= 0x7A)
-}
-
-fn is_digit(chr: char) -> bool {
-  chr as u8 >= 0x30 && chr as u8 <= 0x39
-}
-
-fn is_alphanumeric(chr: char) -> bool {
-  is_alphabetic(chr) || is_digit(chr)
-}
-
-fn is_space(chr: char) -> bool {
-  chr == ' ' || chr == '\t'
-}
-
 fn is_line_ending_or_comment(chr: char) -> bool {
   chr == ';' || chr == '\n'
 }
@@ -39,10 +23,6 @@ fn space_or_line_ending(i: &str) -> IResult<&str, &str> {
   is_a(" \r\n")(i)
 }
 
-fn right_bracket(c: char) -> bool {
-  c == ']'
-}
-
 fn category(i: &str) -> IResult<&str, &str> {
   terminated(delimited(char('['), take_while(|c| c != ']'), char(']')), opt(is_a(" \r\n")))(i)
 }
diff --git a/tests/multiline.rs b/tests/multiline.rs
index 06c2ece..cca19ec 100644
--- a/tests/multiline.rs
+++ b/tests/multiline.rs
@@ -1,4 +1,3 @@
-#[macro_use]
 extern crate nom;
 
 use nom::{