go/doc: clarify that NewFromFiles caller must filter by GOOS/GOARCH

The most well known and important build constraints to take into
account when rendering package documentation are the GOOS/GOARCH
values. Make it more clear in the NewFromFiles documentation that
they are a part of all build constraints that the caller is
responsible for filtering out.

Also suggest the "go/build".Context.MatchFile method for performing
file matching. The logic to perform build context file matching is
subtle and has many rules that aren't well known (for example,
taking the gc or gccgo compiler into account). It is currently the
only exported API in the standard library that implements this logic,
and it would be unfortunate if people attempt to re-create it because
they don't realize it is already available.

Updates #23864

Change-Id: I3c5901e7081acf79125b2d429ec3aa3b58416ed7
Reviewed-on: https://go-review.googlesource.com/c/go/+/218477
Reviewed-by: Robert Griesemer <gri@golang.org>

diff --git a/src/go/doc/doc.go b/src/go/doc/doc.go
index 0e50af04f624ab4ecf0e0d6de68e7a4e287065d2..79d38998e7b51164eb427dfa819049584947837f 100644 (file)
--- a/src/go/doc/doc.go
+++ b/src/go/doc/doc.go
@@ -138,9 +138,12 @@ func New(pkg *ast.Package, importPath string, mode Mode) *Package {
 // NewFromFiles computes documentation for a package.
 //
 // The package is specified by a list of *ast.Files and corresponding
-// file set, which must not be nil. NewFromFiles does not skip files
-// based on build constraints, so it is the caller's responsibility to
-// provide only the files that are matched by the build context.
+// file set, which must not be nil.
+// NewFromFiles uses all provided files when computing documentation,
+// so it is the caller's responsibility to provide only the files that
+// match the desired build context. "go/build".Context.MatchFile can
+// be used for determining whether a file matches a build context with
+// the desired GOOS and GOARCH values, and other build constraints.
 // The import path of the package is specified by importPath.
 //
 // Examples found in _test.go files are associated with the corresponding