Improve documentation

Author: Kobzol

collector/compile-benchmarks/README.md

@@ -1,13 +1,13 @@
-# The Benchmark Suite
+# The Compile-time Benchmark Suite
 
-This file describes the programs in the benchmark suite and explains why they
+This file describes the programs in the compile-time benchmark suite and explains why they
 were included.
 
 The suite changes over time. Sometimes the code for a benchmark is updated, in
 which case a small suffix will be added (starting with "-2", then "-3", and so
 on.)
 
-There are three categories of benchmarks, **Primary**, **Secondary**, and
+There are three categories of compile-time benchmarks, **Primary**, **Secondary**, and
 **Stable**.
 
 ## Primary
@@ -198,7 +198,7 @@ Rust code being written today.
       applies correctly, e.g. `target/release/collector bench_local +nightly
       --id Test --profiles=Check --scenarios=IncrPatched
       --include=$NEW_BENCHMARK`
-  - Add the new entry to `collector/benchmarks/README.md`.
+  - Add the new entry to `collector/compile-benchmarks/README.md`.
   - `git add` the `Cargo.lock` file, if it's not already part of the
     benchmark's committed code.
     - If the benchmark has a `.gitignore` file that contains `Cargo.lock`,
@@ -232,7 +232,7 @@ Rust code being written today.
 - In the first commit just remove the old code.
   - Do this with `git rm -r` on the directory.
 - In the second commit do everything else.
-  - Remove the entry from `collector/benchmarks/README.md`.
+  - Remove the entry from `collector/compile-benchmarks/README.md`.
   - `git grep` for occurrences of the old benchmark name (e.g. in
     `.github/workflows/ci.yml` or `ci/check-*.sh`) and see if anything needs
     changing... usually not.

collector/runtime-benchmarks/README.md

@@ -0,0 +1,9 @@
+# The Runtime Benchmark Suite
+This directory contains various pieces of code for which we measure how fast do they execute
+when they are compiled with a specific version of `rustc`.
+
+The benchmarks are located in crates that are part of the `runtime-benchmarks` workspace. Each crate
+contains a set of benchmarks defined using named closures.
+
+Benchmarks are divided into sub-crates so that some benchmarks can use various versions of dependency
+crates and also so that they are grouped together by a relevant area (e.g. hashmap benchmarks).

collector/runtime-benchmarks/hashmap/src/main.rs

@@ -4,6 +4,7 @@ use benchlib::benchmark::BenchmarkSuite;
 fn main() {
     let mut suite = BenchmarkSuite::new();
 
+    /// Measures how long does it take to insert 10 thousand numbers into a `hashbrown` hashmap.
     suite.register("hashmap-insert-10k", || {
         let mut map =
             hashbrown::HashMap::with_capacity_and_hasher(10000, fxhash::FxBuildHasher::default());