Add grammar documentation.

Author: teymour-aldridge

fuzzcheck/src/mutators/grammar/grammar.rs

@@ -23,11 +23,26 @@ pub enum Grammar {
 pub fn regex(s: &str) -> Rc<Grammar> {
     grammar_from_regex(s)
 }
+
 #[no_coverage]
+/// Creates an [`Rc<Grammar>`] which outputs characters in the given range.
+///
+/// For example, to generate characters in the range 'a' to 'z' (inclusive), one
+/// could use this code
+///
+/// ```
+/// let a_to_z = literal_ranges('a'..='z');
+/// ```
 pub fn literal_ranges(ranges: Vec<RangeInclusive<char>>) -> Rc<Grammar> {
     Rc::new(Grammar::Literal(ranges))
 }
+
 #[no_coverage]
+/// Creates an [`Rc<Grammar>`] which matches a single character literal.
+///
+/// ```
+/// let l = literal('l');
+/// ```
 pub fn literal(l: char) -> Rc<Grammar> {
     Rc::new(Grammar::Literal(vec![l..=l]))
 }
@@ -48,15 +63,31 @@ where
     };
     Rc::new(Grammar::Literal(vec![start..=end]))
 }
+
+/// Produces a grammar which will choose between the provided grammars.
 #[no_coverage]
 pub fn alternation(gs: impl IntoIterator<Item = Rc<Grammar>>) -> Rc<Grammar> {
     Rc::new(Grammar::Alternation(gs.into_iter().collect()))
 }
+
+/// Produces a grammar which will concatenate the output of all the provided
+/// grammars together, in order.
+///
+/// For example, the grammar
+/// ```
+/// concatenation([
+///     regex("fuzz"),
+///     regex("check")
+/// ])
+/// ```
+/// would output "fuzzcheck".
 #[no_coverage]
 pub fn concatenation(gs: impl IntoIterator<Item = Rc<Grammar>>) -> Rc<Grammar> {
     Rc::new(Grammar::Concatenation(gs.into_iter().collect()))
 }
+
 #[no_coverage]
+/// Repeats the provided grammar some number of times in the given range.
 pub fn repetition<R>(gs: Rc<Grammar>, range: R) -> Rc<Grammar>
 where
     R: RangeBounds<usize>,
@@ -75,10 +106,19 @@ where
 }
 
 #[no_coverage]
+/// Used to indicate a point of recursion to Fuzzcheck. Should be combined with
+/// [`recursive`].
+///
+/// See the module documentation ([`super`]) for an example on how to use it.
 pub fn recurse(g: &Weak<Grammar>) -> Rc<Grammar> {
     Rc::new(Grammar::Recurse(g.clone()))
 }
+
 #[no_coverage]
+/// Creates a recursive grammar. This function should be combined with
+/// [`recurse`] to make recursive calls.
+///
+/// See the module documentation ([`super`]) for an example on how to use it.
 pub fn recursive(data_fn: impl Fn(&Weak<Grammar>) -> Rc<Grammar>) -> Rc<Grammar> {
     Rc::new(Grammar::Recursive(Rc::new_cyclic(|g| {
         Rc::try_unwrap(data_fn(g)).unwrap()