Merge bitcoin/bitcoin#22292: bench, doc: benchmarking updates and fixups

d8513fe41102dcbfc05235f3b95e33eb1878f880 doc: update doc/benchmarking.md (Jon Atack)
84e2d5b78181d08b258c77f9c9c4e1bb7fdaa451 bench: bench_bitcoin.cpp help fixups (Jon Atack)
10f4ce20783cbbcb0c0997c605452d9e60827e6d bench: bench.h fixes and improvements (Jon Atack)

Pull request description:

  Fixups and updates I noticed while writing benchmarks for #22284.

ACKs for top commit:
  za-kk:
    ACK d8513fe41102dcbfc05235f3b95e33eb1878f880
  theStack:
    ACK d8513fe41102dcbfc05235f3b95e33eb1878f880 🚤

Tree-SHA512: d494956b5d6a3329e98e8b6f4405a10613b8fce51a04bbf4493d8b3497b8d5b177c1a9a3eeb828796eb4edb92b0ace769595151e223671c0dc8f09bcf631ebb5

3 files changed, 34 insertions, 19 deletions

diff --git a/doc/benchmarking.md b/doc/benchmarking.md
index b6cd86eafe..84d5f2c444 100644
--- a/doc/benchmarking.md
+++ b/doc/benchmarking.md
@@ -8,8 +8,10 @@ thread queue, wallet balance.
 Running
 ---------------------
 
-For benchmarks purposes you only need to compile `bitcoin_bench`. Beware of configuring without `--enable-debug` as this would impact
-benchmarking by unlatching log printers and lock analysis.
+For benchmarking, you only need to compile `bitcoin_bench`.  The bench runner
+warns if you configure with `--enable-debug`, but consider if building without
+it will impact the benchmark(s) you are interested in by unlatching log printers
+and lock analysis.
 
     make -C src bitcoin_bench
 
@@ -19,19 +21,28 @@ After compiling bitcoin-core, the benchmarks can be run with:
 
 The output will look similar to:
 ```
-|             ns/byte |              byte/s | error % | benchmark
-|--------------------:|--------------------:|--------:|:----------------------------------------------
-|               64.13 |       15,592,356.01 |    0.1% | `Base58CheckEncode`
-|               24.56 |       40,722,672.68 |    0.2% | `Base58Decode`
+|               ns/op |                op/s |    err% |     total | benchmark
+|--------------------:|--------------------:|--------:|----------:|:----------
+|       57,927,463.00 |               17.26 |    3.6% |      0.66 | `AddrManAdd`
+|          677,816.00 |            1,475.33 |    4.9% |      0.01 | `AddrManGetAddr`
+
+...
+
+|             ns/byte |              byte/s |    err% |     total | benchmark
+|--------------------:|--------------------:|--------:|----------:|:----------
+|              127.32 |        7,854,302.69 |    0.3% |      0.00 | `Base58CheckEncode`
+|               31.95 |       31,303,226.99 |    0.2% |      0.00 | `Base58Decode`
+
 ...
 ```
 
 Help
 ---------------------
 
-    src/bench/bench_bitcoin --help
+    src/bench/bench_bitcoin -?
 
-To print options like scaling factor or per-benchmark filter.
+To print the various options, like listing the benchmarks without running them
+or using a regex filter to only run certain benchmarks.
 
 Notes
 ---------------------
diff --git a/src/bench/bench.h b/src/bench/bench.h
index 22f06d8cb8..c4fcd80e33 100644
--- a/src/bench/bench.h
+++ b/src/bench/bench.h
@@ -18,16 +18,19 @@
 /*
  * Usage:
 
-static void CODE_TO_TIME(benchmark::Bench& bench)
+static void NameOfYourBenchmarkFunction(benchmark::Bench& bench)
 {
-    ... do any setup needed...
-    nanobench::Config().run([&] {
-       ... do stuff you want to time...
+    ...do any setup needed...
+
+    bench.run([&] {
+         ...do stuff you want to time; refer to src/bench/nanobench.h
+            for more information and the options that can be passed here...
     });
-    ... do any cleanup needed...
+
+    ...do any cleanup needed...
 }
 
-BENCHMARK(CODE_TO_TIME);
+BENCHMARK(NameOfYourBenchmarkFunction);
 
  */
 
@@ -55,7 +58,8 @@ public:
 
     static void RunAll(const Args& args);
 };
-}
+} // namespace benchmark
+
 // BENCHMARK(foo) expands to:  benchmark::BenchRunner bench_11foo("foo", foo);
 #define BENCHMARK(n) \
     benchmark::BenchRunner PASTE2(bench_, PASTE2(__LINE__, n))(STRINGIZE(n), n);
diff --git a/src/bench/bench_bitcoin.cpp b/src/bench/bench_bitcoin.cpp
index 135659f87f..aab777cac1 100644
--- a/src/bench/bench_bitcoin.cpp
+++ b/src/bench/bench_bitcoin.cpp
@@ -16,11 +16,11 @@ static void SetupBenchArgs(ArgsManager& argsman)
 {
     SetupHelpOptions(argsman);
 
-    argsman.AddArg("-list", "List benchmarks without executing them", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
+    argsman.AddArg("-asymptote=n1,n2,n3,...", "Test asymptotic growth of the runtime of an algorithm, if supported by the benchmark", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
     argsman.AddArg("-filter=<regex>", strprintf("Regular expression filter to select benchmark by name (default: %s)", DEFAULT_BENCH_FILTER), ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
-    argsman.AddArg("-asymptote=n1,n2,n3,...", strprintf("Test asymptotic growth of the runtime of an algorithm, if supported by the benchmark"), ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
-    argsman.AddArg("-output_csv=<output.csv>", "Generate CSV file with the most important benchmark results.", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
-    argsman.AddArg("-output_json=<output.json>", "Generate JSON file with all benchmark results.", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
+    argsman.AddArg("-list", "List benchmarks without executing them", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
+    argsman.AddArg("-output_csv=<output.csv>", "Generate CSV file with the most important benchmark results", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
+    argsman.AddArg("-output_json=<output.json>", "Generate JSON file with all benchmark results", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
 }
 
 // parses a comma separated list like "10,20,30,50"