benchmarks: add documentation

Fixes issue 9131.

Change-Id: Iff8677e72f40131a8bff15b8303e15118402e5c8
Reviewed-on: https://go-review.googlesource.com/1383
Reviewed-by: Andrew Gerrand <adg@golang.org>

README

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.
+

bench/bench.go

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 (

build/build.go

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 (

driver/driver.go

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 (

garbage/garbage.go

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 (

http/http.go

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 (

json/json.go

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 (