more doc

libafl/src/bolts/ownedref.rs

@@ -1,6 +1,11 @@
+//! Wrappers that abstracts references (or pointers) and owned data accesses.
+// The serialization is towards owned, allowing to serialize pointers without troubles.
+
 use alloc::{boxed::Box, vec::Vec};
+use core::{clone::Clone, fmt::Debug};
 use serde::{Deserialize, Deserializer, Serialize, Serializer};
 
+/// Wrap a reference and convert to a Box on serialize
 #[derive(Clone, Debug)]
 pub enum Ptr<'a, T: 'a + ?Sized> {
     Ref(&'a T),
@@ -40,6 +45,8 @@ impl<'a, T: Sized> AsRef<T> for Ptr<'a, T> {
     }
 }
 
+/// Wrap a mutable reference and convert to a Box on serialize
+#[derive(Debug)]
 pub enum PtrMut<'a, T: 'a + ?Sized> {
     Ref(&'a mut T),
     Owned(Box<T>),
@@ -87,6 +94,8 @@ impl<'a, T: Sized> AsMut<T> for PtrMut<'a, T> {
     }
 }
 
+/// Wrap a slice and convert to a Vec on serialize
+#[derive(Clone, Debug)]
 pub enum Slice<'a, T: 'a + Sized> {
     Ref(&'a [T]),
     Owned(Vec<T>),
@@ -125,6 +134,8 @@ impl<'a, T: Sized> Slice<'a, T> {
     }
 }
 
+/// Wrap a mutable slice and convert to a Vec on serialize
+#[derive(Debug)]
 pub enum SliceMut<'a, T: 'a + Sized> {
     Ref(&'a mut [T]),
     Owned(Vec<T>),
@@ -170,6 +181,7 @@ impl<'a, T: Sized> SliceMut<'a, T> {
     }
 }
 
+/// Wrap a C-style pointer and convert to a Box on serialize
 #[derive(Clone, Debug)]
 pub enum Cptr<T: Sized> {
     Cptr(*const T),
@@ -206,6 +218,8 @@ impl<T: Sized> AsRef<T> for Cptr<T> {
     }
 }
 
+/// Wrap a C-style mutable pointer and convert to a Box on serialize
+#[derive(Clone, Debug)]
 pub enum CptrMut<T: Sized> {
     Cptr(*mut T),
     Owned(Box<T>),
@@ -250,6 +264,8 @@ impl<T: Sized> AsMut<T> for CptrMut<T> {
     }
 }
 
+/// Wrap a C-style pointer to an array (with size= and convert to a Vec on serialize
+#[derive(Clone, Debug)]
 pub enum Array<T: Sized> {
     Cptr((*const T, usize)),
     Owned(Vec<T>),
@@ -285,6 +301,7 @@ impl<T: Sized> Array<T> {
     }
 }
 
+/// Wrap a C-style mutable pointer to an array (with size= and convert to a Vec on serialize
 #[derive(Clone, Debug)]
 pub enum ArrayMut<T: Sized> {
     Cptr((*mut T, usize)),

libafl/src/bolts/serdeany.rs

@@ -1,4 +1,5 @@
 //! Poor-rust-man's downcasts for stuff we send over the wire (or shared maps)
+
 use serde::{Deserialize, Deserializer, Serialize, Serializer};
 
 use alloc::boxed::Box;

libafl/src/corpus/minimizer.rs

@@ -1,3 +1,6 @@
+//! The Minimizer schedulers are a family of corpus schedulers that feed the fuzzer
+// with testcases only from a subset of the total corpus.
+
 use crate::{
     bolts::serdeany::SerdeAny,
     corpus::{Corpus, CorpusScheduler, Testcase},
@@ -43,6 +46,7 @@ impl Default for TopRatedsMetadata {
     }
 }
 
+/// Compute the favor factor of a testcase. Lower is better.
 pub trait FavFactor<I>
 where
     I: Input,
@@ -50,6 +54,8 @@ where
     fn compute(testcase: &mut Testcase<I>) -> Result<u64, Error>;
 }
 
+/// Multiply the testcase size with the execution time.
+/// This favors small and quick testcases.
 pub struct LenTimeMulFavFactor<I>
 where
     I: Input + HasLen,
@@ -67,6 +73,9 @@ where
     }
 }
 
+/// The Minimizer scheduler employs a genetic algorithm to compute a subset of the
+/// corpus that exercise all the requested features (e.g. all the coverage seen so far)
+/// prioritizing testcases using FavFactor
 pub struct MinimizerCorpusScheduler<C, CS, F, I, M, R, S>
 where
     CS: CorpusScheduler<I, S>,
@@ -230,8 +239,11 @@ where
     }
 }
 
+/// A MinimizerCorpusScheduler with LenTimeMulFavFactor to prioritize quick and small testcases
 pub type LenTimeMinimizerCorpusScheduler<C, CS, I, M, R, S> =
     MinimizerCorpusScheduler<C, CS, LenTimeMulFavFactor<I>, I, M, R, S>;
 
+/// A MinimizerCorpusScheduler with LenTimeMulFavFactor to prioritize quick and small testcases
+/// that exercise all the entries registered in the MapIndexesMetadata
 pub type IndexesLenTimeMinimizerCorpusScheduler<C, CS, I, R, S> =
     MinimizerCorpusScheduler<C, CS, LenTimeMulFavFactor<I>, I, MapIndexesMetadata, R, S>;

libafl/src/corpus/mod.rs

@@ -63,6 +63,8 @@ where
     fn current_mut(&mut self) -> &mut Option<usize>;
 }
 
+/// The scheduler define how the fuzzer requests a testcase from the corpus.
+/// It has hooks to corpus add/replace/remove to allow complex scheduling algorithms to collect data.
 pub trait CorpusScheduler<I, S>
 where
     I: Input,
@@ -96,6 +98,7 @@ where
     fn next(&self, state: &mut S) -> Result<usize, Error>;
 }
 
+/// Feed the fuzzer simpply with a random testcase on request
 pub struct RandCorpusScheduler<C, I, R, S>
 where
     S: HasCorpus<C, I> + HasRand<R>,

libafl/src/corpus/queue.rs

@@ -1,4 +1,4 @@
-//! The queue corpus implements an afl-like queue mechanism
+//! The queue corpus scheduler implements an AFL-like queue mechanism
 
 use alloc::borrow::ToOwned;
 use core::marker::PhantomData;
@@ -10,6 +10,7 @@ use crate::{
     Error,
 };
 
+/// Walk the corpus in a queue-like fashion
 pub struct QueueCorpusScheduler<C, I, S>
 where
     S: HasCorpus<C, I>,
@@ -25,7 +26,7 @@ where
     C: Corpus<I>,
     I: Input,
 {
-    /// Gets the next entry at random
+    /// Gets the next entry in the queue
     fn next(&self, state: &mut S) -> Result<usize, Error> {
         if state.corpus().count() == 0 {
             Err(Error::Empty("No entries in corpus".to_owned()))