cmd/doc: show documentation for explicitly-requested identifiers regardless of the `-u` flag
#33,133 opened on Jul 16, 2019
Repository metrics
- Stars
- (133,883 stars)
- PR merge metrics
- (No merged PRs in 30d)
Description
What version of Go are you using (go version)?
~/go/src$ go version
go version devel +87bf0b5c51 Tue Jul 16 13:17:46 2019 -0400 linux/amd64
What did you do?
~/go/src$ go doc go/build.getToolDir
What did you expect to see?
~/go/src$ go doc go/build.getToolDir
package build // import "go/build"
func getToolDir() string
getToolDir returns the default value of ToolDir.
What did you see instead?
~/go/src$ go doc go/build.getToolDir
package build // import "go/build"
doc: no symbol getToolDir in package go/build
exit status 1
~/go/src$ go doc -u go/build.getToolDir
package build // import "go/build"
func getToolDir() string
getToolDir returns the default value of ToolDir.
The doc command by default hides all unexported identifiers, even those explicitly requested by the user. To coax it to display the requested result, you have to pass the -u flag, which has the secondary (and often unwanted) effect of displaying unexported fields and methods on the requested identifier.
Moreover, that behavior is inconsistent with the behavior for internal packages, for which go doc will happily display documentation even without the -u flag.
Instead, the -u flag should control only the behavior for nested declarations — variables, constants, types, functions, fields, and/or methods associated with the requested identifier — not the requested identifier itself.
CC @robpike @mvdan @ianthehat