cmd/go: test whether alldocs.go is up to date

A common error is to update the help text for a command in cmd/go, but
fail to update alldocs.go, which actually prints the help text for the
most common commands.

Add a test that the long-form documentation help text matches the
contents of alldocs.go, which will fail the build if we fail to keep
the documentation in sync. We can get fancier with the test output if
this is not sufficient.

Fixes golang/go#26735.

Change-Id: I2509765315eeb0f362633d812343d1324a01b73b
Reviewed-on: https://go-review.googlesource.com/127920
Run-TryBot: Kevin Burke <kev@inburke.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

src/cmd/go/alldocs.go

@@ -1003,13 +1003,16 @@
 //
 // Usage:
 //
-// 	go mod graph
+// 	go mod graph [-dot]
 //
 // Graph prints the module requirement graph (with replacements applied)
 // in text form. Each line in the output has two space-separated fields: a module
 // and one of its requirements. Each module is identified as a string of the form
 // path@version, except for the main module, which has no @version suffix.
 //
+// The -dot flag generates the output in graphviz format that can be used
+// with a tool like dot to visually render the dependency graph.
+//
 //
 // Initialize new module in current directory
 //

src/cmd/go/help_test.go

+// Copyright 2018 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// +build !nacl
+
+package main_test
+
+import (
+	"bytes"
+	"io/ioutil"
+	"testing"
+
+	"cmd/go/internal/help"
+)
+
+func TestDocsUpToDate(t *testing.T) {
+	buf := new(bytes.Buffer)
+	// Match the command in mkalldocs.sh that generates alldocs.go.
+	help.Help(buf, []string{"documentation"})
+	data, err := ioutil.ReadFile("alldocs.go")
+	if err != nil {
+		t.Fatalf("error reading alldocs.go: %v", err)
+	}
+	if !bytes.Equal(data, buf.Bytes()) {
+		t.Errorf("alldocs.go is not up to date; run mkalldocs.sh to regenerate it")
+	}
+}

src/cmd/go/internal/help/help.go

@@ -20,16 +20,16 @@ import (
 )
 
 // Help implements the 'help' command.
-func Help(args []string) {
+func Help(w io.Writer, args []string) {
 	// 'go help documentation' generates doc.go.
 	if len(args) == 1 && args[0] == "documentation" {
-		fmt.Println("// Copyright 2011 The Go Authors. All rights reserved.")
-		fmt.Println("// Use of this source code is governed by a BSD-style")
-		fmt.Println("// license that can be found in the LICENSE file.")
-		fmt.Println()
-		fmt.Println("// Code generated by mkalldocs.sh; DO NOT EDIT.")
-		fmt.Println("// Edit the documentation in other files and rerun mkalldocs.sh to generate this one.")
-		fmt.Println()
+		fmt.Fprintln(w, "// Copyright 2011 The Go Authors. All rights reserved.")
+		fmt.Fprintln(w, "// Use of this source code is governed by a BSD-style")
+		fmt.Fprintln(w, "// license that can be found in the LICENSE file.")
+		fmt.Fprintln(w)
+		fmt.Fprintln(w, "// Code generated by mkalldocs.sh; DO NOT EDIT.")
+		fmt.Fprintln(w, "// Edit the documentation in other files and rerun mkalldocs.sh to generate this one.")
+		fmt.Fprintln(w)
 		buf := new(bytes.Buffer)
 		PrintUsage(buf, base.Go)
 		usage := &base.Command{Long: buf.String()}
@@ -42,8 +42,8 @@ func Help(args []string) {
 			cmds = append(cmds, cmd)
 			cmds = append(cmds, cmd.Commands...)
 		}
-		tmpl(&commentWriter{W: os.Stdout}, documentationTemplate, cmds)
-		fmt.Println("package main")
+		tmpl(&commentWriter{W: w}, documentationTemplate, cmds)
+		fmt.Fprintln(w, "package main")
 		return
 	}
 

src/cmd/go/main.go

@@ -95,7 +95,7 @@ func main() {
 
 	cfg.CmdName = args[0] // for error messages
 	if args[0] == "help" {
-		help.Help(args[1:])
+		help.Help(os.Stdout, args[1:])
 		return
 	}
 
@@ -199,7 +199,7 @@ BigCmdLoop:
 				}
 				if args[0] == "help" {
 					// Accept 'go mod help' and 'go mod help foo' for 'go help mod' and 'go help mod foo'.
-					help.Help(append(strings.Split(cfg.CmdName, " "), args[1:]...))
+					help.Help(os.Stdout, append(strings.Split(cfg.CmdName, " "), args[1:]...))
 					return
 				}
 				cfg.CmdName += " " + args[0]

src/cmd/go/mkalldocs.sh

@@ -6,6 +6,8 @@
 set -e
 
 go build -o go.latest
+# If the command used to generate alldocs.go changes, update TestDocsUpToDate in
+# help_test.go.
 ./go.latest help documentation >alldocs.go
 gofmt -w alldocs.go
 rm go.latest