cmd/doc: show documentation for explicitly-requested identifiers regardless of the -u flag

[bcmills]

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

[mvdan]

This sounds like a good idea to me.

[kawakami-o3]

I will work on this.

[gopherbot]

Change https://golang.org/cl/195201 mentions this issue: cmd/doc: show documentation for explicitly-requested identifiers regardless of the -u flag