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 #26735.

Change-Id: I2509765315eeb0f362633d812343d1324a01b73b
Reviewed-on: https://go-review.googlesource.com/127920
Run-TryBot: Kevin Burke <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
Reviewed-by: Brad Fitzpatrick <[email protected]>

Author: kevinburke

src/cmd/go/alldocs.go

@@ -0,0 +1,28 @@
+// 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/help_test.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/internal/help/help.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/main.go

@@ -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