cmdline tools: Auto-generate doc.go file using "go generate".
Originally I had planned to write yet another cmdline program
that would take the directory containing the main package for
each cmdline tool, and generate the doc.go file by running help
for the tool.
However I realized we should use "go run" to run the tool, to
ensure we're running the most recent version of the code. At
which point it's simpler just to run bash to run the tool and
generate the doc.go file.
Also fixed the help topic header, so that godoc recognizes it as
a section header. Specifically it isn't allowed to include
parens, but is allowed to include a dash.
Change-Id: Ie1980263d42be8e85ee7c6709812f62d83df83d8
diff --git a/tools/debug/main.go b/tools/debug/main.go
index bc021ef..ffa2f5b 100644
--- a/tools/debug/main.go
+++ b/tools/debug/main.go
@@ -1,4 +1,12 @@
-// A command-line tool to interface with the debug server.
+// The following enables go generate to generate the doc.go file.
+// Things to look out for:
+// 1) go:generate evaluates double-quoted strings into a single argument.
+// 2) go:generate performs $NAME expansion, so the bash cmd can't contain '$'.
+// 3) We generate into a *.tmp file first, otherwise go run will pick up the
+// initially empty *.go file, and fail.
+//
+//go:generate bash -c "{ echo -e '// This file was auto-generated via go generate.\n// DO NOT UPDATE MANUALLY\n\n/*' && veyron go run *.go help -style=godoc ... && echo -e '*/\npackage main'; } > ./doc.go.tmp && mv ./doc.go.tmp ./doc.go"
+
package main
import (
