From 4ef38bad4340b5c8100ec2522264c57f0522aa2d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Szalay=20Krist=C3=B3f?=
 <32012862+littletof@users.noreply.github.com>
Date: Wed, 3 Jun 2020 19:44:37 +0200
Subject: [PATCH] docs: benchmarking (#6075)

---
 std/testing/README.md     | 93 ++++++++++++++++++++++++++-------------
 std/testing/bench_test.ts |  1 -
 2 files changed, 62 insertions(+), 32 deletions(-)

diff --git a/std/testing/README.md b/std/testing/README.md
index 4a92492056..42ce49d5c8 100644
--- a/std/testing/README.md
+++ b/std/testing/README.md
@@ -137,9 +137,20 @@ Deno.test("fails", async function (): Promise<void> {
 });
 ```
 
-### Benching Usage
+## Benching
 
-Basic usage:
+With this module you can benchmark your code and get information on how is it
+performing.
+
+### Basic usage:
+
+Benchmarks can be registered using the `bench` function, where you can define a
+code, that should be benchmarked. `b.start()` has to be called at the start of
+the part you want to benchmark and `b.stop()` at the end of it, otherwise an
+error will be thrown.
+
+After that simply calling `runBenchmarks()` will benchmark all registered
+benchmarks and log the results in the commandline.
 
 ```ts
 import { runBenchmarks, bench } from "https://deno.land/std/testing/bench.ts";
@@ -167,43 +178,63 @@ bench({
 });
 ```
 
+Running specific benchmarks using regular expressions:
+
+```ts
+runBenchmarks({ only: /desired/, skip: /exceptions/ });
+```
+
+### Processing benchmark results
+
+`runBenchmarks()` returns a `Promise<BenchmarkRunResult>`, so you can process
+the benchmarking results yourself. It contains detailed results of each
+benchmark's run as `BenchmarkResult` s.
+
+```ts
+runBenchmarks()
+  .then((results: BenchmarkRunResult) => {
+    console.log(results);
+  })
+  .catch((error: Error) => {
+    // ... errors if benchmark was badly constructed
+  });
+```
+
+### Processing benchmarking progress
+
+`runBenchmarks()` accepts an optional progress handler callback function, so you
+can get information on the progress of the running benchmarking.
+
+Using `{ silent: true }` means you wont see the default progression logs in the
+commandline.
+
+```ts
+runBenchmarks({ silent: true }, (p: BenchmarkRunProgress) => {
+  // initial progress data
+  if (p.state === ProgressState.BenchmarkingStart) {
+    console.log(
+      `Starting benchmarking. Queued: ${p.queued.length}, filtered: ${p.filtered}`
+    );
+  }
+  // ...
+});
+```
+
 #### Benching API
 
 ##### `bench(benchmark: BenchmarkDefinition | BenchmarkFunction): void`
 
 Registers a benchmark that will be run once `runBenchmarks` is called.
 
-##### `runBenchmarks(opts?: BenchmarkRunOptions): Promise<void>`
+##### `runBenchmarks(opts?: BenchmarkRunOptions, progressCb?: (p: BenchmarkRunProgress) => void): Promise<BenchmarkRunResult>`
 
 Runs all registered benchmarks serially. Filtering can be applied by setting
 `BenchmarkRunOptions.only` and/or `BenchmarkRunOptions.skip` to regular
-expressions matching benchmark names.
+expressions matching benchmark names. Default progression logs can be turned off
+with the `BenchmarkRunOptions.silent` flag.
 
-##### Other exports
+##### `clearBenchmarks(opts?: BenchmarkClearOptions): void`
 
-```ts
-/** Provides methods for starting and stopping a benchmark clock. */
-export interface BenchmarkTimer {
-  start: () => void;
-  stop: () => void;
-}
-
-/** Defines a benchmark through a named function. */
-export interface BenchmarkFunction {
-  (b: BenchmarkTimer): void | Promise<void>;
-  name: string;
-}
-
-/** Defines a benchmark definition with configurable runs. */
-export interface BenchmarkDefinition {
-  func: BenchmarkFunction;
-  name: string;
-  runs?: number;
-}
-
-/** Defines runBenchmark's run constraints by matching benchmark names. */
-export interface BenchmarkRunOptions {
-  only?: RegExp;
-  skip?: RegExp;
-}
-```
+Clears all registered benchmarks, so calling `runBenchmarks()` after it wont run
+them. Filtering can be applied by setting `BenchmarkRunOptions.only` and/or
+`BenchmarkRunOptions.skip` to regular expressions matching benchmark names.
diff --git a/std/testing/bench_test.ts b/std/testing/bench_test.ts
index 8e34b27a99..e36451fb0d 100644
--- a/std/testing/bench_test.ts
+++ b/std/testing/bench_test.ts
@@ -237,7 +237,6 @@ test({
     const benchingResults = await runBenchmarks(
       { skip: /skip/, silent: true },
       (progress) => {
-        // needs to be deep copied
         progressCallbacks.push(progress);
       }
     );