Merge pull request #35 from teymour-aldridge/docs

Add some more documentation.

Author: loiclec

fuzzcheck/src/mutators/filter.rs

@@ -2,10 +2,31 @@ use std::any::Any;
 
 use crate::Mutator;
 
+/// A [`FilterMutator`] provides a way to filter values outputted by a mutator.
+/// Given any [`Mutator<Value=T>`] and a function [`Fn(&T) -> bool`] it creates
+/// a new mutator which can generate all the values of `T` the underlying
+/// mutator can, except those for which the filtering function returns false.
 pub struct FilterMutator<M, F> {
-    pub mutator: M,
-    pub filter: F,
+    mutator: M,
+    filter: F,
 }
+
+impl<M, F> FilterMutator<M, F> {
+    /// Creates a new [`FilterMutator`].
+    ///
+    /// Note that the mutator will filter all values for which the filtering
+    /// function returns _false_.
+    pub fn new<T>(mutator: M, filter: F) -> FilterMutator<M, F>
+    where
+        M: Mutator<T>,
+        T: Clone + 'static,
+        F: Fn(&T) -> bool,
+        Self: 'static,
+    {
+        FilterMutator { mutator, filter }
+    }
+}
+
 impl<T, M, F> Mutator<T> for FilterMutator<M, F>
 where
     M: Mutator<T>,

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()

fuzzcheck/src/mutators/mod.rs

@@ -140,9 +140,9 @@ where
     #[no_coverage]
     fn filter<F>(self, filter: F) -> FilterMutator<Self, F>
     where
-        F: Fn(&T) -> bool,
+        F: Fn(&T) -> bool + 'static,
     {
-        FilterMutator { mutator: self, filter }
+        FilterMutator::new(self, filter)
     }
     /// Create a mutator which wraps `self` and transforms the values generated by `self`
     /// using the `map` closure. The second closure, `parse`, should apply the opposite