From: Kevin Burke Date: Sat, 4 Aug 2018 17:01:54 +0000 (-0700) Subject: cmd/go: test whether alldocs.go is up to date X-Git-Tag: go1.12beta1~1412 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=d169a429c5f9f1d20114e09fb131bc205b5a74f9;p=gostls13.git 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 TryBot-Result: Gobot Gobot Reviewed-by: Brad Fitzpatrick --- diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go index c67e3f5a1c..1585dd5b1f 100644 --- 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 index 0000000000..ec6a9d11cb --- /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 a80afe36c4..312a29590f 100644 --- 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 0639b4d2ca..f64ffeb670 100644 --- 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 72886db1ea..4e7a509805 100755 --- 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