cmd/go: document convention to signify generated code.

This change updates the go tool's documentation under the section
"Generate Go files by processing source" to mention the convention that
generated source files should have a line of text that matches the
following regular expression:

    ^// Code generated .* DO NOT EDIT\.$

Previously, the canonical documentation for this convention
(https://golang.org/s/generatedcode) referenced Rob Pike's comment at
https://golang.org/issue/13560#issuecomment-288457920. This change
merely moves that information to a more visible place.

Updates #25433.

Change-Id: I804d95d307d1dc68cb28da3750ebe9090178c474
Reviewed-on: https://go-review.googlesource.com/118756
Reviewed-by: Rob Pike <r@golang.org>

diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index d37942b738f34ecba33fed0e4d9e69c5f979b768..ffc6505c1dbc8339c3d22f97775092dca13d36ec 100644 (file)
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -419,6 +419,12 @@
 // (gofmt), a fully qualified path (/usr/you/bin/mytool), or a
 // command alias, described below.
 //
+// To convey to humans and machine tools that code is generated,
+// generated source should have a line early in the file that
+// matches the following regular expression (in Go syntax):
+//
+//     ^// Code generated .* DO NOT EDIT\.$
+//
 // Note that go generate does not parse the file, so lines that look
 // like directives in comments or multiline strings will be treated
 // as directives.

diff --git a/src/cmd/go/internal/generate/generate.go b/src/cmd/go/internal/generate/generate.go
index 441f91aea83797ff0bb888abfeda1e8b383d3cfb..971844d2ea15a231ea68e56d206a942b470fadfe 100644 (file)
--- a/src/cmd/go/internal/generate/generate.go
+++ b/src/cmd/go/internal/generate/generate.go
@@ -47,6 +47,12 @@ that can be run locally. It must either be in the shell path
 (gofmt), a fully qualified path (/usr/you/bin/mytool), or a
 command alias, described below.
 
+To convey to humans and machine tools that code is generated,
+generated source should have a line early in the file that
+matches the following regular expression (in Go syntax):
+
+       ^// Code generated .* DO NOT EDIT\.$
+
 Note that go generate does not parse the file, so lines that look
 like directives in comments or multiline strings will be treated
 as directives.