Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
bcmills opened this issue Jul 16, 2019 · 3 comments

Comments

@bcmills
Copy link
Member

@bcmills bcmills commented Jul 16, 2019

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

@bcmills bcmills added this to the Go1.14 milestone Jul 16, 2019
@bcmills bcmills changed the title cmd/doc: do not require an explicit `-u` flag if an unexported identifier is requested explicitly cmd/doc: do not require the `-u` flag if an unexported identifier is requested explicitly Jul 16, 2019
@bcmills bcmills changed the title cmd/doc: do not require the `-u` flag if an unexported identifier is requested explicitly cmd/doc: show documentation for explicitly-requested identifiers regardless of the `-u` flag Jul 16, 2019
@mvdan
Copy link
Member

@mvdan mvdan commented Jul 26, 2019

This sounds like a good idea to me.

@bcmills bcmills added the NeedsFix label Aug 1, 2019
@bcmills bcmills added the help wanted label Aug 1, 2019
@bcmills bcmills modified the milestones: Go1.14, Unplanned Aug 1, 2019
@kawakami-o3
Copy link
Contributor

@kawakami-o3 kawakami-o3 commented Aug 2, 2019

I will work on this.

@gopherbot
Copy link

@gopherbot gopherbot commented Sep 14, 2019

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants
You can’t perform that action at this time.