cmd/go: clarify that -coverpkg uses import paths

This change amends the long-form help output for 'go help build' and
'go help testflag' to specify that the '-coverpkg' flag operates
explicitly on import paths as well as package names. Import paths are
fundamental for precise specification of packages versus unqualified
package names, and the naming of the flag '-coverpkg' and its original
documentation leads a user to assume that it only operates on the
simple, unqualified package name form. The situation warrants
clarification.

Fixes #69653

src/cmd/go/alldocs.go

@@ -146,10 +146,11 @@
 //		Sets -cover.
 //	-coverpkg pattern1,pattern2,pattern3
 //		For a build that targets package 'main' (e.g. building a Go
-//		executable), apply coverage analysis to each package matching
+//		executable), apply coverage analysis to each package whose
-//		the patterns. The default is to apply coverage analysis to
+//		import path matches the patterns. The default is to apply
-//		packages in the main Go module. See 'go help packages' for a
+//		coverage analysis to packages in the main Go module. See
-//		description of package patterns.  Sets -cover.
+//		'go help packages' for a description of package patterns.
+//		Sets -cover.
 //	-v
 //		print the names of packages as they are compiled.
 //	-work
@@ -2947,6 +2948,12 @@
 // - "cmd" expands to the Go repository's commands and their
 // internal libraries.
 //
+// Package names match against fully-qualified import paths or patterns that
+// match against any number of import paths. For instance, "fmt" refers to the
+// standard library's package fmt, but "http" alone for package http would not
+// match the import path "net/http" from the standard library. Instead, the
+// complete import path "net/http" must be used.
+//
 // Import paths beginning with "cmd/" only match source code in
 // the Go repository.
 //
@@ -2976,7 +2983,10 @@
 // unique prefix that belongs to you. For example, paths used
 // internally at Google all begin with 'google', and paths
 // denoting remote repositories begin with the path to the code,
-// such as 'github.com/user/repo'.
+// such as 'github.com/user/repo'. Package patterns should include this prefix.
+// For instance, a package called 'http' residing under 'github.com/user/repo',
+// would be addressed with the fully-qualified pattern:
+// 'github.com/user/repo/http'.
 //
 // Packages in a program need not have unique package names,
 // but there are two reserved package names with special meaning.
@@ -3093,10 +3103,10 @@
 //	    Sets -cover.
 //
 //	-coverpkg pattern1,pattern2,pattern3
-//	    Apply coverage analysis in each test to packages matching the patterns.
+//	    Apply coverage analysis in each test to packages whose import paths
-//	    The default is for each test to analyze only the package being tested.
+//	    match the patterns. The default is for each test to analyze only
-//	    See 'go help packages' for a description of package patterns.
+//	    the package being tested. See 'go help packages' for a description
-//	    Sets -cover.
+//	    of package patterns. Sets -cover.
 //
 //	-cpu 1,2,4
 //	    Specify a list of GOMAXPROCS values for which the tests, benchmarks or

src/cmd/go/internal/help/helpdoc.go

@@ -64,6 +64,12 @@ Go library.
 - "cmd" expands to the Go repository's commands and their
 internal libraries.
 
+Package names match against fully-qualified import paths or patterns that
+match against any number of import paths. For instance, "fmt" refers to the
+standard library's package fmt, but "http" alone for package http would not
+match the import path "net/http" from the standard library. Instead, the
+complete import path "net/http" must be used.
+
 Import paths beginning with "cmd/" only match source code in
 the Go repository.
 
@@ -93,7 +99,10 @@ By convention, this is arranged by starting each path with a
 unique prefix that belongs to you. For example, paths used
 internally at Google all begin with 'google', and paths
 denoting remote repositories begin with the path to the code,
-such as 'github.com/user/repo'.
+such as 'github.com/user/repo'. Package patterns should include this prefix.
+For instance, a package called 'http' residing under 'github.com/user/repo',
+would be addressed with the fully-qualified pattern:
+'github.com/user/repo/http'.
 
 Packages in a program need not have unique package names,
 but there are two reserved package names with special meaning.

src/cmd/go/internal/test/test.go

@@ -235,10 +235,10 @@ control the execution of any test:
 	    Sets -cover.
 
 	-coverpkg pattern1,pattern2,pattern3
-	    Apply coverage analysis in each test to packages matching the patterns.
+	    Apply coverage analysis in each test to packages whose import paths
-	    The default is for each test to analyze only the package being tested.
+	    match the patterns. The default is for each test to analyze only
-	    See 'go help packages' for a description of package patterns.
+	    the package being tested. See 'go help packages' for a description
-	    Sets -cover.
+	    of package patterns. Sets -cover.
 
 	-cpu 1,2,4
 	    Specify a list of GOMAXPROCS values for which the tests, benchmarks or

src/cmd/go/internal/work/build.go

@@ -104,10 +104,11 @@ and test commands:
 		Sets -cover.
 	-coverpkg pattern1,pattern2,pattern3
 		For a build that targets package 'main' (e.g. building a Go
-		executable), apply coverage analysis to each package matching
+		executable), apply coverage analysis to each package whose
-		the patterns. The default is to apply coverage analysis to
+		import path matches the patterns. The default is to apply
-		packages in the main Go module. See 'go help packages' for a
+		coverage analysis to packages in the main Go module. See
-		description of package patterns.  Sets -cover.
+		'go help packages' for a description of package patterns.
+		Sets -cover.
 	-v
 		print the names of packages as they are compiled.
 	-work