go/build: correct value of .Doc field

Build could use the package comment from test files to populate the .Doc
field on *Package.

As go list uses this data and several packages in the standard library
have tests with package comments, this lead to:

$ go list -f '{{.Doc}}' flag container/heap image
These examples demonstrate more intricate uses of the flag package.
This example demonstrates an integer heap built using the heap interface.
This example demonstrates decoding a JPEG image and examining its pixels.

This change now only examines non-test files when attempting to populate
.Doc, resulting in the expected behavior:

$ gotip list -f '{{.Doc}}' flag container/heap image
Package flag implements command-line flag parsing.
Package heap provides heap operations for any type that implements heap.Interface.
Package image implements a basic 2-D image library.

Fixes #23594

Change-Id: I37171c26ec5cc573efd273556a05223c6f675968
Reviewed-on: https://go-review.googlesource.com/96976
Run-TryBot: Daniel Martí <mvdan@mvdan.cc>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Daniel Martí <mvdan@mvdan.cc>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

src/go/build/build.go

@@ -813,7 +813,8 @@ Found:
 			})
 			p.InvalidGoFiles = append(p.InvalidGoFiles, name)
 		}
-		if pf.Doc != nil && p.Doc == "" {
+		// Grab the first package comment as docs, provided it is not from a test file.
+		if pf.Doc != nil && p.Doc == "" && !isTest && !isXTest {
 			p.Doc = doc.Synopsis(pf.Doc.Text())
 		}
 

src/go/build/build_test.go

@@ -395,3 +395,19 @@ func TestImportDirTarget(t *testing.T) {
 		t.Errorf("p.PkgTargetRoot == %q, p.PkgObj == %q, want non-empty", p.PkgTargetRoot, p.PkgObj)
 	}
 }
+
+// TestIssue23594 prevents go/build from regressing and populating Package.Doc
+// from comments in test files.
+func TestIssue23594(t *testing.T) {
+	// Package testdata/doc contains regular and external test files
+	// with comments attached to their package declarations. The names of the files
+	// ensure that we see the comments from the test files first.
+	p, err := ImportDir("testdata/doc", 0)
+	if err != nil {
+		t.Fatalf("could not import testdata: %v", err)
+	}
+
+	if p.Doc != "Correct" {
+		t.Fatalf("incorrectly set .Doc to %q", p.Doc)
+	}
+}

src/go/build/testdata/doc/a_test.go

@@ -0,0 +1,2 @@
+// Doc from xtests
+package doc_test

src/go/build/testdata/doc/b_test.go

@@ -0,0 +1 @@
+package doc_test

src/go/build/testdata/doc/c_test.go

@@ -0,0 +1 @@
+package doc

src/go/build/testdata/doc/d_test.go

@@ -0,0 +1,2 @@
+// Doc from regular tests.
+package doc

src/go/build/testdata/doc/e.go

@@ -0,0 +1 @@
+package doc

src/go/build/testdata/doc/f.go

@@ -0,0 +1,2 @@
+// Correct
+package doc