benchmarks: add documentation
Fixes issue 9131.
Change-Id: Iff8677e72f40131a8bff15b8303e15118402e5c8
Reviewed-on: https://go-review.googlesource.com/1383
Reviewed-by: Andrew Gerrand <adg@golang.org>
diff --git a/README b/README
index 425ffc3..9113cbc 100644
--- a/README
+++ b/README
@@ -1 +1,48 @@
-This subrepository holds benchmarks used by the perf dashboard.
+This subrepository holds benchmarks used by the Go performance dashboard:
+http://build.golang.org/perf
+
+All benchmarks are compiled into a single binary, to build it execute:
+
+ go install golang.org/x/benchmarks/bench
+
+When you run the binary without any flags, it prints comma-separated list of
+available benchmarks:
+
+ ./bench
+ build,garbage,http,json
+
+To run a benchmark execute:
+
+ ./bench -bench=json
+
+The binary has a number of flags to control benchmark duration, etc.
+Run 'bench -help' to get the full list of flags.
+
+When the benchmarking finishes, the binary prints results:
+
+ GOPERF-METRIC:allocated=7872994
+ GOPERF-METRIC:allocs=105483
+ GOPERF-METRIC:cputime=196757680
+ GOPERF-METRIC:gc-pause-one=5762425
+ GOPERF-METRIC:gc-pause-total=2650715
+ GOPERF-METRIC:rss=63655936
+ GOPERF-METRIC:sys-gc=3407366
+ GOPERF-METRIC:sys-heap=53575680
+ GOPERF-METRIC:sys-other=5253938
+ GOPERF-METRIC:sys-stack=229376
+ GOPERF-METRIC:sys-total=62466360
+ GOPERF-METRIC:time=206958902
+ GOPERF-FILE:cpuprof=/tmp/19.prof.txt
+ GOPERF-FILE:memprof=/tmp/20.prof.txt
+
+Description of metrics is available at:
+https://golang.org/wiki/PerfDashboard
+
+A typical usage of the benchmarking binary from dashboard builder is:
+
+ ./builder -filelock=builderlock -build=false -bench -benchtime=5s \
+ -benchnum=5 -benchmem=1024 -benchcpu=1,2,4,8,16 \
+ -benchaffinity=85,85,85,21845 windows-amd64-perf
+
+To submit changes to this repository, see http://golang.org/doc/contribute.html.
+
diff --git a/bench/bench.go b/bench/bench.go
index 44de9ee..5a0bb77 100644
--- a/bench/bench.go
+++ b/bench/bench.go
@@ -2,6 +2,16 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+/*
+Bench contains benchmarks for the Go performance dashboard:
+ http://build.golang.org/perf
+Run without flags to get list of available benchmarks:
+ ./bench
+ build,garbage,http,json
+To run a benchmark execute:
+ ./bench -bench=json
+See the README file for more details.
+*/
package main // import "golang.org/x/benchmarks/bench"
import (
diff --git a/build/build.go b/build/build.go
index 796e36c..f7a7b38 100644
--- a/build/build.go
+++ b/build/build.go
@@ -2,6 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Build is a benchmark that examines compiler and linker performance.
+// It executes 'go build -a cmd/go'.
package build // import "golang.org/x/benchmarks/build"
import (
diff --git a/driver/driver.go b/driver/driver.go
index d58c523..85644a7 100644
--- a/driver/driver.go
+++ b/driver/driver.go
@@ -2,15 +2,14 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// This file contains common benchmarking logic shared between benchmarks.
+// Driver contains common benchmarking logic shared between benchmarks.
// It defines the main function which calls one of the benchmarks registered
// with Register function.
// When a benchmark is invoked it has 2 choices:
-// 1. Do whatever it wants, fill and return Result object.
-// 2. Call Benchmark helper function and provide benchmarking function
-// func(N uint64), similar to standard testing benchmarks. The rest is handled
-// by the driver.
-
+// 1. Do whatever it wants, fill and return Result object.
+// 2. Call Benchmark helper function and provide benchmarking function
+// func(N uint64), similar to standard testing benchmarks. The rest is handled
+// by the driver.
package driver // import "golang.org/x/benchmarks/driver"
import (
diff --git a/garbage/garbage.go b/garbage/garbage.go
index fd0db1c..8e2bb94 100644
--- a/garbage/garbage.go
+++ b/garbage/garbage.go
@@ -2,6 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Garbage is a benchmark that stresses garbage collector.
+// It repeatedly parses net/http package with go/parser and then discards results.
package garbage // import "golang.org/x/benchmarks/garbage"
import (
diff --git a/http/http.go b/http/http.go
index 8ae610e..10144d8 100644
--- a/http/http.go
+++ b/http/http.go
@@ -2,6 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// HTTP is a benchmark that examines client/server http performance.
package http // import "golang.org/x/benchmarks/http"
import (
diff --git a/json/json.go b/json/json.go
index 937910f..3507163 100644
--- a/json/json.go
+++ b/json/json.go
@@ -4,7 +4,6 @@
// JSON benchmark marshals and unmarshals ~2MB json string
// with a tree-like object hierarchy, in 4*GOMAXPROCS goroutines.
-
package json // import "golang.org/x/benchmarks/json"
import (
