qbit/go
1
0
Fork 0
mirror of https://github.com/golang/go synced 2024-09-30 03:24:39 -06:00
Code Releases Activity

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

Browse Source 
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>
This commit is contained in:
Dmitri Shuralyov 2020-02-07 11:15:11 -05:00
parent dff55c1f76
commit 6a8164a254
1 changed files with 6 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
src/go/doc/doc.go
View File

@ -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