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>

diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index c67e3f5a1c3bc47b87be67afedcc5de7c7302af1..1585dd5b1f3f5c97c54044320417c7d6a01ddec4 100644 (file)
--- a/src/cmd/go/alldocs.go
+++ b/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
 //

diff --git a/src/cmd/go/help_test.go b/src/cmd/go/help_test.go
new file mode 100644 (file)
index 0000000..ec6a9d1
--- /dev/null
+++ b/src/cmd/go/help_test.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")
+       }
+}

diff --git a/src/cmd/go/internal/help/help.go b/src/cmd/go/internal/help/help.go
index a80afe36c412c4de955f36f21fa60e13b7eeb18b..312a29590f43f0fbd65aea08de3caff15cdce6bc 100644 (file)
--- a/src/cmd/go/internal/help/help.go
+++ b/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
        }
 

diff --git a/src/cmd/go/main.go b/src/cmd/go/main.go
index 0639b4d2ca09f62a4f580ac4ac25e13bea345a65..f64ffeb6708f9d61a9ff551a1473f97dd02fa5b7 100644 (file)
--- a/src/cmd/go/main.go
+++ b/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]

diff --git a/src/cmd/go/mkalldocs.sh b/src/cmd/go/mkalldocs.sh
index 72886db1eac7e695067246756abdabc7bf54969f..4e7a50980541e7453f608d2a9598c4f3c27fbf93 100755 (executable)
--- a/src/cmd/go/mkalldocs.sh
+++ b/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