Better documentation headers (clippy) (AFLplusplus#2501)

* Better documentation headers (clippy)

* more doc

* more fixes

* Even more

* more

* even more

* concrete

* fmt

* even more more

* tiny typo

* more

* more

* More

* more

* more docs?

* more docs

libafl/src/corpus/inmemory_ondisk.rs

@@ -1,4 +1,5 @@
 //! The [`InMemoryOnDiskCorpus`] stores [`Testcase`]s to disk.
+//!
 //! Additionally, _all_ of them are kept in memory.
 //! For a lower memory footprint, consider using [`crate::corpus::CachedOnDiskCorpus`]
 //! which only stores a certain number of [`Testcase`]s and removes additional ones in a FIFO manner.

libafl/src/corpus/ondisk.rs

@@ -1,4 +1,5 @@
 //! The [`OnDiskCorpus`] stores all [`Testcase`]s to disk.
+//!
 //! It _never_ keeps any of them in memory.
 //! This is a good solution for solutions that are never reused, or for *very* memory-constraint environments.
 //! For any other occasions, consider using [`crate::corpus::CachedOnDiskCorpus`]

libafl/src/events/events_hooks/mod.rs

@@ -1,4 +1,5 @@
 //! Hooks for event managers, especifically these are used to hook before `handle_in_client`.
+//!
 //! This will allow user to define pre/post-processing code when the event manager receives any message from
 //! other clients
 use libafl_bolts::ClientId;

libafl/src/events/launcher.rs

@@ -480,6 +480,8 @@ where
     }
 }
 
+/// A Launcher that minimizes re-execution of shared testcases.
+///
 /// Provides a Launcher, which can be used to launch a fuzzing run on a specified list of cores with a single main and multiple secondary nodes
 /// This is for centralized, the 4th argument of the closure should mean if this is the main node.
 #[cfg(all(unix, feature = "std", feature = "fork"))]

libafl/src/events/llmp/restarting.rs

@@ -338,6 +338,7 @@ pub enum ManagerKind {
 }
 
 /// Sets up a restarting fuzzer, using the [`StdShMemProvider`], and standard features.
+///
 /// The restarting mgr is a combination of restarter and runner, that can be used on systems with and without `fork` support.
 /// The restarter will spawn a new process each time the child crashes or timeouts.
 #[cfg(feature = "std")]
@@ -368,6 +369,7 @@ where
 }
 
 /// Sets up a restarting fuzzer, using the [`StdShMemProvider`], and standard features.
+///
 /// The restarting mgr is a combination of restarter and runner, that can be used on systems with and without `fork` support.
 /// The restarter will spawn a new process each time the child crashes or timeouts.
 /// This one, additionally uses the timeobserver for the adaptive serialization
@@ -400,7 +402,9 @@ where
         .launch()
 }
 
-/// Provides a `builder` which can be used to build a [`RestartingMgr`], which is a combination of a
+/// Provides a `builder` which can be used to build a [`RestartingMgr`].
+///
+/// The [`RestartingMgr`] is is a combination of a
 /// `restarter` and `runner`, that can be used on systems both with and without `fork` support. The
 /// `restarter` will start a new process each time the child crashes or times out.
 #[cfg(feature = "std")]

libafl/src/events/mod.rs

@@ -68,7 +68,8 @@ pub mod multi_machine;
 #[cfg(all(unix, feature = "std"))]
 pub static mut EVENTMGR_SIGHANDLER_STATE: ShutdownSignalData = ShutdownSignalData {};
 
-/// A signal handler for catching ctrl-c.
+/// A signal handler for catching `ctrl-c`.
+///
 /// The purpose of this signal handler is solely for calling `exit()` with a specific exit code 100
 /// In this way, the restarting manager can tell that we really want to exit
 #[cfg(all(unix, feature = "std"))]

libafl/src/events/simple.rs

@@ -310,7 +310,9 @@ where
     }
 }
 
-/// Provides a `builder` which can be used to build a [`SimpleRestartingEventManager`], which is a combination of a
+/// Provides a `builder` which can be used to build a [`SimpleRestartingEventManager`].
+///
+/// The [`SimpleRestartingEventManager`] is a combination of a
 /// `restarter` and `runner`, that can be used on systems both with and without `fork` support. The
 /// `restarter` will start a new process each time the child crashes or times out.
 #[cfg(feature = "std")]

libafl/src/events/tcp.rs

@@ -1074,7 +1074,8 @@ pub enum TcpManagerKind {
 }
 
 /// Sets up a restarting fuzzer, using the [`StdShMemProvider`], and standard features.
-/// The restarting mgr is a combination of restarter and runner, that can be used on systems with and without `fork` support.
+///
+/// The [`TcpRestartingEventManager`] is a combination of restarter and runner, that can be used on systems with and without `fork` support.
 /// The restarter will spawn a new process each time the child crashes or timeouts.
 #[cfg(feature = "std")]
 #[allow(clippy::type_complexity)]
@@ -1103,7 +1104,9 @@ where
         .launch()
 }
 
-/// Provides a `builder` which can be used to build a [`TcpRestartingMgr`], which is a combination of a
+/// Provides a `builder` which can be used to build a [`TcpRestartingMgr`].
+///
+/// The [`TcpRestartingMgr`] is a combination of a
 /// `restarter` and `runner`, that can be used on systems both with and without `fork` support. The
 /// `restarter` will start a new process each time the child crashes or times out.
 #[cfg(feature = "std")]

libafl/src/executors/command.rs

@@ -154,6 +154,7 @@ where
 }
 
 /// A `CommandExecutor` is a wrapper around [`std::process::Command`] to execute a target as a child process.
+///
 /// Construct a `CommandExecutor` by implementing [`CommandConfigurator`] for a type of your choice and calling [`CommandConfigurator::into_executor`] on it.
 /// Instead, you can use [`CommandExecutor::builder()`] to construct a [`CommandExecutor`] backed by a [`StdCommandConfigurator`].
 pub struct CommandExecutor<OT, S, T> {

libafl/src/executors/differential.rs

@@ -1,4 +1,5 @@
 //! Executor for differential fuzzing.
+//!
 //! It wraps two executors that will be run after each other with the same input.
 //! In comparison to the [`crate::executors::CombinedExecutor`] it also runs the secondary executor in `run_target`.
 //!

libafl/src/executors/forkserver.rs

@@ -531,6 +531,7 @@ impl Forkserver {
 }
 
 /// This [`Executor`] can run binaries compiled for AFL/AFL++ that make use of a forkserver.
+///
 /// Shared memory feature is also available, but you have to set things up in your code.
 /// Please refer to AFL++'s docs. <https://github.com/AFLplusplus/AFLplusplus/blob/stable/instrumentation/README.persistent_mode.md>
 pub struct ForkserverExecutor<OT, S, SP>

libafl/src/executors/inprocess_fork/mod.rs

@@ -37,10 +37,11 @@ pub(crate) type ForkHandlerFuncPtr = unsafe fn(
 
 /// The inner structure of `InProcessForkExecutor`.
 pub mod inner;
-/// A version of `InProcessForkExecutor` with a state accessible from the harness.
 pub mod stateful;
 
-/// The `InProcessForkExecutor` with no user hooks. On Linux, when fuzzing a Rust target, set `panic = "abort"` in your `Cargo.toml` (see [Cargo documentation](https://doc.rust-lang.org/cargo/reference/profiles.html#panic)).
+/// The `InProcessForkExecutor` with no user hooks.
+///
+/// On Linux, when fuzzing a Rust target, set `panic = "abort"` in your `Cargo.toml` (see [Cargo documentation](https://doc.rust-lang.org/cargo/reference/profiles.html#panic)).
 /// Else panics can not be caught by `LibAFL`.
 pub type InProcessForkExecutor<'a, H, OT, S, SP, EM, Z> =
     GenericInProcessForkExecutor<'a, H, (), OT, S, SP, EM, Z>;
@@ -80,7 +81,9 @@ where
     }
 }
 
-/// [`GenericInProcessForkExecutor`] is an executor that forks the current process before each execution. On Linux, when fuzzing a Rust target, set `panic = "abort"` in your `Cargo.toml` (see [Cargo documentation](https://doc.rust-lang.org/cargo/reference/profiles.html#panic)).
+/// [`GenericInProcessForkExecutor`] is an executor that forks the current process before each execution.
+///
+/// On Linux, when fuzzing a Rust target, set `panic = "abort"` in your `Cargo.toml` (see [Cargo documentation](https://doc.rust-lang.org/cargo/reference/profiles.html#panic)).
 /// Else panics can not be caught by `LibAFL`.
 pub struct GenericInProcessForkExecutor<'a, H, HT, OT, S, SP, EM, Z>
 where

libafl/src/executors/inprocess_fork/stateful.rs

@@ -1,4 +1,7 @@
-//! The `StatefulGenericInProcessForkExecutor` to do forking before executing the harness in-processly. Harness can access internal state.
+//! A version of `InProcessForkExecutor` with a state accessible from the harness.
+//!
+//! The `StatefulGenericInProcessForkExecutor` to do forking before executing the harness in-process.
+//! The harness can access internal state.
 use core::{
     fmt::{self, Debug, Formatter},
     marker::PhantomData,

libafl/src/feedbacks/concolic.rs

@@ -1,4 +1,5 @@
 //! Concolic feedback for concolic fuzzing.
+//!
 //! It is used to attach concolic tracing metadata to the testcase.
 //! This feedback should be used in combination with another feedback as this feedback always considers testcases
 //! to be not interesting.
@@ -23,6 +24,7 @@ use crate::{
 };
 
 /// The concolic feedback. It is used to attach concolic tracing metadata to the testcase.
+///
 /// This feedback should be used in combination with another feedback as this feedback always considers testcases
 /// to be not interesting.
 /// Requires a [`ConcolicObserver`] to observe the concolic trace.

libafl/src/feedbacks/custom_filename.rs

@@ -19,6 +19,7 @@ use crate::{
 };
 
 /// A [`CustomFilenameToTestcaseFeedback`] takes a closure which returns a filename for the testcase.
+///
 /// Is never interesting (use with an Eager OR).
 /// Note: Use only in conjunction with a `Corpus` type that writes to disk.
 /// Note: If used as part of the `Objective` chain, then it will only apply to testcases which are

libafl/src/feedbacks/mod.rs

@@ -720,8 +720,9 @@ pub type FastAndFeedback<A, B, S> = CombinedFeedback<A, B, LogicFastAnd, S>;
 /// will call all feedbacks functions even if not necessary to conclude the result
 pub type EagerOrFeedback<A, B, S> = CombinedFeedback<A, B, LogicEagerOr, S>;
 
-/// Combine two feedbacks with an fast OR operation,
-/// might skip calling feedbacks functions if not necessary to conclude the result.
+/// Combine two feedbacks with an fast OR operation - fast.
+///
+/// This might skip calling feedbacks functions if not necessary to conclude the result.
 /// This means any feedback that is not first might be skipped, use caution when using with
 /// `TimeFeedback`
 pub type FastOrFeedback<A, B, S> = CombinedFeedback<A, B, LogicFastOr, S>;
@@ -1141,6 +1142,8 @@ impl<T> FeedbackFactory<DiffExitKindFeedback, T> for DiffExitKindFeedback {
     }
 }
 
+/// A [`Feedback`] to track execution time.
+///
 /// Nop feedback that annotates execution time in the new testcase, if any
 /// for this Feedback, the testcase is never interesting (use with an OR).
 /// It decides, if the given [`TimeObserver`] value of a run is interesting.

libafl/src/feedbacks/transferred.rs

@@ -16,7 +16,9 @@ use crate::{
 pub const TRANSFERRED_FEEDBACK_NAME: Cow<'static, str> =
     Cow::Borrowed("transferred_feedback_internal");
 
-/// Metadata which denotes whether we are currently transferring an input. Implementors of
+/// Metadata which denotes whether we are currently transferring an input.
+///
+/// Implementors of
 /// multi-node communication systems (like [`crate::events::LlmpEventManager`]) should wrap any
 /// [`crate::EvaluatorObservers::evaluate_input_with_observers`] or
 /// [`crate::ExecutionProcessor::process_execution`] calls with setting this metadata to true/false

libafl/src/inputs/bytessub.rs

@@ -15,6 +15,7 @@ use crate::inputs::HasMutatorBytes;
 
 /// The [`BytesSubInput`] makes it possible to use [`crate::mutators::Mutator`]`s` that work on
 /// inputs implementing the [`HasMutatorBytes`] for a sub-range of this input.
+///
 /// For example, we can do the following:
 /// ```rust
 /// # extern crate alloc;

libafl/src/inputs/encoded.rs

@@ -1,5 +1,6 @@
-//! The `EncodedInput` is the "normal" input, a map of codes, that can be sent directly to the client
-//! (As opposed to other, more abstract, inputs, like an Grammar-Based AST Input)
+//! The `EncodedInput` is the "normal" input, a map of codes, that can be sent directly to the client.
+//!
+//! This is different to other, more abstract inputs, like an Grammar-Based AST Input.
 //! See also [the paper on token-level fuzzing](https://www.usenix.org/system/files/sec21-salls.pdf)
 
 #[cfg(feature = "regex")]

libafl/src/mutators/gramatron.rs

@@ -1,4 +1,5 @@
-//! [`GramatronRandomMutator`] ist a random mutator using grammar automatons to perform grammar-aware fuzzing.
+//! [`GramatronRandomMutator`] is a random mutator using grammar automatons to perform grammar-aware fuzzing.
+//!
 //! See the original gramatron repo [`Gramatron`](https://github.com/HexHive/Gramatron) for more details.
 use alloc::{borrow::Cow, vec::Vec};
 use core::cmp::max;

libafl/src/mutators/mod.rs

@@ -1,4 +1,6 @@
-//! [`Mutator`]`s` mutate input during fuzzing. These can be used standalone or in combination with other mutators to explore the input space more effectively.
+//! [`Mutator`]`s` mutate input during fuzzing.
+//!
+//! These can be used standalone or in combination with other mutators to explore the input space more effectively.
 //! You can read more about mutators in the [libAFL book](https://aflplus.plus/libafl-book/core_concepts/mutator.html)
 pub mod scheduled;
 use core::fmt;

libafl/src/mutators/mopt_mutator.rs

@@ -1,4 +1,6 @@
-//! The `MOpt` mutation scheduler used in AFL++. It uses a modified Particle Swarm Optimization algorithm to determine an optimal distribution of mutators.
+//! The `MOpt` mutation scheduler used in AFL++.
+//!
+//! It uses a modified Particle Swarm Optimization algorithm to determine an optimal distribution of mutators.
 //! See <https://github.com/puppet-meteor/MOpt-AFL> and <https://www.usenix.org/conference/usenixsecurity19/presentation/lyu>
 use alloc::{borrow::Cow, string::ToString, vec::Vec};
 use core::{
@@ -21,6 +23,7 @@ use crate::{
 };
 
 /// A Struct for managing MOpt-mutator parameters.
+///
 /// There are 2 modes for `MOpt` scheduler, the core fuzzing mode and the pilot fuzzing mode.
 /// In short, in the pilot fuzzing mode, the fuzzer employs several `swarms` to compute the probability to choose the mutation operator.
 /// On the other hand, in the core fuzzing mode, the fuzzer chooses the best `swarms`, which was determined during the pilot fuzzing mode, to compute the probability to choose the mutation operator.

libafl/src/mutators/tuneable.rs

@@ -1,4 +1,5 @@
 //! An extension to the `ScheduledMutator` which schedules multiple mutations internally.
+//!
 //! Instead of a random mutator for a random amount of iterations, we can run
 //! a specific mutator for a specified amount of iterations
 

libafl/src/observers/concolic/mod.rs

@@ -9,15 +9,19 @@ use core::{
 #[cfg(feature = "std")]
 use serde::{Deserialize, Serialize};
 
-/// A `SymExprRef` identifies a [`SymExpr`] in a trace. Reading a `SymExpr` from a trace will always also yield its
+/// A `SymExprRef` identifies a [`SymExpr`] in a trace.
+///
+/// Reading a `SymExpr` from a trace will always also yield its
 /// `SymExprRef`, which can be used later in the trace to identify the `SymExpr`.
 /// It is also never zero, which allows for efficient use of `Option<SymExprRef>`.
 ///
 /// In a trace, `SymExprRef`s are monotonically increasing and start at 1.
 /// `SymExprRef`s are not valid across traces.
 pub type SymExprRef = NonZeroUsize;
 
-/// [`Location`]s are code locations encountered during concolic tracing, that are constructed from pointers, but not always in a meaningful way.
+/// [`Location`]s are code locations encountered during concolic tracing
+///
+/// [`Location`]s are constructed from pointers, but not always in a meaningful way.
 /// Therefore, a location is an opaque value that can only be compared against itself.
 ///
 /// It is possible to get at the underlying value using [`Into::into`], should this restriction be too inflexible for your usecase.

libafl/src/observers/map/mod.rs

@@ -35,13 +35,15 @@ pub use multi_map::*;
 pub mod owned_map;
 pub use owned_map::*;
 
+/// A trait indicating tracking of observed map values after testcase execution
+///
 /// Trait marker which indicates that this [`MapObserver`] is tracked for indices or novelties.
 /// Implementors of feedbacks similar to [`crate::feedbacks::MapFeedback`] may wish to use this to
 /// ensure that edge metadata is recorded as is appropriate for the provided observer.
 ///
 /// If you get a type constraint failure for your map due to this type being unfulfilled, you must
 /// call [`CanTrack::track_indices`] or [`CanTrack::track_novelties`] **at
-/// the initialisation site of your map**.
+/// the initialization site of your map**.
 ///
 /// This trait allows various components which interact with map metadata to ensure that the
 /// information they need is actually recorded by the map feedback.

libafl/src/observers/stdio.rs

@@ -1,3 +1,5 @@
+//! Observers for `stdout` and `stderr`
+//!
 //! The [`StdOutObserver`] and [`StdErrObserver`] observers look at the stdout of a program
 //! The executor must explicitly support these observers.
 //! For example, they are supported on the [`crate::executors::CommandExecutor`].

libafl/src/schedulers/minimizer.rs

@@ -1,5 +1,5 @@
-//! The Minimizer schedulers are a family of corpus schedulers that feed the fuzzer
-//! with testcases only from a subset of the total corpus.
+//! The [`MinimizerScheduler`]`s` are a family of corpus schedulers that feed the fuzzer
+//! with [`Testcase`]`s` only from a subset of the total [`Corpus`].
 
 use alloc::vec::Vec;
 use core::{any::type_name, cmp::Ordering, marker::PhantomData};
@@ -68,8 +68,9 @@ impl Default for TopRatedsMetadata {
 }
 
 /// The [`MinimizerScheduler`] 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 [`Testcase`]`s` using [`TestcaseScore`]
+/// corpus that exercise all the requested features.
+///
+/// E.g., it can use all the coverage seen so far to prioritize [`Testcase`]`s` using a [`TestcaseScore`].
 #[derive(Debug, Clone)]
 pub struct MinimizerScheduler<CS, F, M, O> {
     base: CS,
@@ -93,7 +94,7 @@ where
     <Self as UsesState>::State: HasCorpus + HasMetadata + HasRand,
     O: CanTrack,
 {
-    /// Replaces the testcase at the given id
+    /// Replaces the [`Testcase`] at the given [`CorpusId`]
     fn on_replace(
         &mut self,
         state: &mut <Self as UsesState>::State,

libafl/src/schedulers/mod.rs

@@ -270,5 +270,6 @@ impl<S> Default for RandScheduler<S> {
 }
 
 /// A [`StdScheduler`] uses the default scheduler in `LibAFL` to schedule [`Testcase`]s.
+///
 /// The current `Std` is a [`RandScheduler`], although this may change in the future, if another [`Scheduler`] delivers better results.
 pub type StdScheduler<S> = RandScheduler<S>;

libafl/src/schedulers/weighted.rs

@@ -1,3 +1,5 @@
+//! An AFL++-style scheduler with a weighted queue.
+//!
 //! The queue corpus scheduler with weighted queue item selection [from AFL++](https://github.com/AFLplusplus/AFLplusplus/blob/1d4f1e48797c064ee71441ba555b29fc3f467983/src/afl-fuzz-queue.c#L32).
 //! This queue corpus scheduler needs calibration stage.
 

libafl/src/stages/generation.rs

@@ -1,3 +1,5 @@
+//! The [`GenStage`] generates a single input and evaluates it.
+//!
 //! A [`Stage`] that generates a single input via a
 //! [`crate::generators::Generator`] and evaluates it using the fuzzer, possibly
 //! adding it to the corpus.

libafl/src/stages/mod.rs

@@ -68,7 +68,6 @@ pub mod concolic;
 #[cfg(feature = "std")]
 pub mod dump;
 pub mod generalization;
-/// The [`generation::GenStage`] generates a single input and evaluates it.
 pub mod generation;
 pub mod logics;
 pub mod power;

libafl/src/stages/pruning.rs

@@ -16,7 +16,8 @@ use crate::{
 use crate::{events::EventRestarter, state::Stoppable};
 
 #[derive(Debug)]
-/// The stage to probablistically disable a corpus entry.
+/// The stage to probabilistically disable a corpus entry.
+///
 /// This stage should be wrapped in a if stage and run only when the fuzzer perform restarting
 /// The idea comes from `https://mschloegel.me/paper/schiller2023fuzzerrestarts.pdf`
 pub struct CorpusPruning<EM> {

libafl/src/stages/push/mod.rs

@@ -1,3 +1,5 @@
+//! [`PushStage`]`s` return inputs instead of calling an executor
+//!
 //! While normal stages call the executor over and over again, push stages turn this concept upside down:
 //! A push stage instead returns an iterator that generates a new result for each time it gets called.
 //! With the new testcase, you will have to take care about testcase execution, manually.

libafl/src/stages/push/mutational.rs

@@ -29,7 +29,9 @@ use crate::{monitors::PerfFeature, state::HasClientPerfMonitor};
 
 /// The default maximum number of mutations to perform per input.
 pub static DEFAULT_MUTATIONAL_MAX_ITERATIONS: usize = 128;
+
 /// A Mutational push stage is the stage in a fuzzing run that mutates inputs.
+///
 /// Mutational push stages will usually have a range of mutations that are
 /// being applied to the input one by one, between executions.
 /// The push version, in contrast to the normal stage, will return each testcase, instead of executing it.

libafl_bolts/src/fs.rs

@@ -29,6 +29,8 @@ pub fn get_unique_std_input_file() -> String {
     format!("{}_{}", INPUTFILE_STD, std::process::id())
 }
 
+/// Write a file atomically
+///
 /// Creates a `.{file_name}.tmp` file, and writes all bytes to it.
 /// After all bytes have been written, the tmp-file is moved to it's original `path`.
 /// This way, on the majority of operating systems, the final file will never be incomplete or racey.