benchmark: document all functions (#7393)

vlib/benchmark/benchmark.v

@@ -26,6 +26,7 @@ pub mut:
 	bfail            string
 }
 
+// new_benchmark returns a `Benchmark` instance on the stack.
 pub fn new_benchmark() Benchmark {
 	return Benchmark{
 		bench_timer: time.new_stopwatch({})
@@ -33,6 +34,7 @@ pub fn new_benchmark() Benchmark {
 	}
 }
 
+// new_benchmark_no_cstep returns a new `Benchmark` instance with step counting disabled.
 pub fn new_benchmark_no_cstep() Benchmark {
 	return Benchmark{
 		bench_timer: time.new_stopwatch({})
@@ -41,6 +43,8 @@ pub fn new_benchmark_no_cstep() Benchmark {
 	}
 }
 
+// new_benchmark_pointer returns a new `Benchmark` instance allocated on the heap.
+// This is useful for long-lived use of `Benchmark` instances.
 pub fn new_benchmark_pointer() &Benchmark {
 	return &Benchmark{
 		bench_timer: time.new_stopwatch({})
@@ -48,14 +52,17 @@ pub fn new_benchmark_pointer() &Benchmark {
 	}
 }
 
+// set_total_expected_steps sets the the total amount of steps the benchmark is expected to take.
 pub fn (mut b Benchmark) set_total_expected_steps(n int) {
 	b.nexpected_steps = n
 }
 
+// stop stops the internal benchmark timer.
 pub fn (mut b Benchmark) stop() {
 	b.bench_timer.stop()
 }
 
+// step increases the step count by 1 and restarts the internal timer.
 pub fn (mut b Benchmark) step() {
 	b.step_timer.restart()
 	if !b.no_cstep {
@@ -63,46 +70,55 @@ pub fn (mut b Benchmark) step() {
 	}
 }
 
+// fail increases the fail count by 1 and stops the internal timer.
 pub fn (mut b Benchmark) fail() {
 	b.step_timer.stop()
 	b.ntotal++
 	b.nfail++
 }
 
+// ok increases the ok count by 1 and stops the internal timer.
 pub fn (mut b Benchmark) ok() {
 	b.step_timer.stop()
 	b.ntotal++
 	b.nok++
 }
 
+// skip increases the skip count by 1 and stops the internal timer.
 pub fn (mut b Benchmark) skip() {
 	b.step_timer.stop()
 	b.ntotal++
 	b.nskip++
 }
 
+// fail_many increases the fail count by `n` and stops the internal timer.
 pub fn (mut b Benchmark) fail_many(n int) {
 	b.step_timer.stop()
 	b.ntotal += n
 	b.nfail += n
 }
 
+// ok_many increases the ok count by `n` and stops the internal timer.
 pub fn (mut b Benchmark) ok_many(n int) {
 	b.step_timer.stop()
 	b.ntotal += n
 	b.nok += n
 }
 
+// neither_fail_nor_ok stops the internal timer.
 pub fn (mut b Benchmark) neither_fail_nor_ok() {
 	b.step_timer.stop()
 }
 
+// start returns a new, running, instance of `Benchmark`.
+// This is a shorthand for calling `new_benchmark().step()`.
 pub fn start() Benchmark {
 	mut b := new_benchmark()
 	b.step()
 	return b
 }
 
+// measure prints the current time spent doing `label`, since the benchmark was started.
 pub fn (mut b Benchmark) measure(label string) i64 {
 	b.ok()
 	res := b.step_timer.elapsed().microseconds()
@@ -111,6 +127,7 @@ pub fn (mut b Benchmark) measure(label string) i64 {
 	return res
 }
 
+// step_message_with_label_and_duration returns a string describing the current step.
 pub fn (b &Benchmark) step_message_with_label_and_duration(label string, msg string, sduration time.Duration) string {
 	timed_line := b.tdiff_in_ms(msg, sduration.microseconds())
 	if b.nexpected_steps > 1 {
@@ -137,26 +154,32 @@ pub fn (b &Benchmark) step_message_with_label_and_duration(label string, msg str
 	return '${label:-5s}${timed_line}'
 }
 
+// step_message_with_label returns a string describing the current step using current time as duration.
 pub fn (b &Benchmark) step_message_with_label(label string, msg string) string {
 	return b.step_message_with_label_and_duration(label, msg, b.step_timer.elapsed())
 }
 
+// step_message returns a string describing the current step.
 pub fn (b &Benchmark) step_message(msg string) string {
 	return b.step_message_with_label('', msg)
 }
 
+// step_message_ok returns a string describing the current step with an standard "OK" label.
 pub fn (b &Benchmark) step_message_ok(msg string) string {
 	return b.step_message_with_label(b_ok, msg)
 }
 
+// step_message_fail returns a string describing the current step with an standard "FAIL" label.
 pub fn (b &Benchmark) step_message_fail(msg string) string {
 	return b.step_message_with_label(b_fail, msg)
 }
 
+// step_message_skip returns a string describing the current step with an standard "SKIP" label.
 pub fn (b &Benchmark) step_message_skip(msg string) string {
 	return b.step_message_with_label(b_skip, msg)
 }
 
+// total_message returns a string with total summary of the benchmark run.
 pub fn (b &Benchmark) total_message(msg string) string {
 	mut tmsg := '${msg}\n                 ok, fail, skip, total = ' + term.ok_message('${b.nok:5d}') + ', ' + if b.nfail > 0 { term.red('${b.nfail:5d}') } else { '${b.nfail:5d}' } + ', ' + if b.nskip > 0 { term.bright_yellow('${b.nskip:5d}') } else { '${b.nskip:5d}' } + ', ' + '${b.ntotal:5d}'
 	if b.verbose {
@@ -172,12 +195,12 @@ pub fn (b &Benchmark) total_message(msg string) string {
 	return spaces + b.tdiff_in_ms(tmsg, b.bench_timer.elapsed().microseconds())
 }
 
-// .total_duration - returns the duration in ms
+// total_duration returns the duration in ms.
 pub fn (b &Benchmark) total_duration() i64 {
 	return b.bench_timer.elapsed().milliseconds()
 }
 
-// //////////////////////////////////////////////////////////////////
+// tdiff_in_ms prefixes `s` with a time difference calculation.
 fn (b &Benchmark) tdiff_in_ms(s string, tdiff i64) string {
 	if b.verbose {
 		return '${f64(tdiff)/1000.0:9.3f} ms $s'