Add some documentation on how to run the facet db fuzzer

milli/src/update/facet/incremental.rs

@@ -1022,6 +1022,35 @@ mod tests {
 
 // fuzz tests
 #[cfg(all(test, fuzzing))]
+/**
+Fuzz test for the incremental indxer.
+
+The fuzz test uses fuzzcheck, a coverage-guided fuzzer.
+See https://github.com/loiclec/fuzzcheck-rs and https://fuzzcheck.neocities.org
+for more information.
+
+It is only run when using the `cargo fuzzcheck` command line tool, which can be installed with:
+```sh
+cargo install cargo-fuzzcheck
+```
+To start the fuzz test, run (from the base folder or from milli/):
+```sh
+cargo fuzzcheck update::facet::incremental::fuzz::fuzz
+```
+and wait a couple minutes to make sure the code was thoroughly tested, then
+hit `Ctrl-C` to stop the fuzzer. The corpus generated by the fuzzer is located in milli/fuzz.
+
+To work on this module with rust-analyzer working properly, add the following to your .cargo/config.toml file:
+```toml
+[build]
+rustflags = ["--cfg",  "fuzzing"]
+```
+
+The fuzz test generates sequences of additions and deletions to the facet database and
+ensures that:
+1. its structure is still internally valid
+2. its content is the same as a trivially correct implementation of the same database
+*/
 mod fuzz {
     use std::borrow::Cow;
     use std::collections::{BTreeMap, HashMap};