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: does not show methods with receivers #18525

Closed
ahmetb opened this issue Jan 5, 2017 · 7 comments
Closed

cmd/doc: does not show methods with receivers #18525

ahmetb opened this issue Jan 5, 2017 · 7 comments

Comments

@ahmetb
Copy link

ahmetb commented Jan 5, 2017

What version of Go are you using (go version)?

go1.7

What did you do?

I ran go doc io.

What did you expect to see?

I expected to see methods

  • func (*PipeWriter) Close
  • func (*PipeWriter) CloseWithError
  • func (*PipeWriter) Write

members of io.Pipewriter in the output, because I see them in godoc io (mind the difference):

$ go doc io
...
...
type LimitedReader struct { ... }
type PipeReader struct { ... }
    func Pipe() (*PipeReader, *PipeWriter)
type PipeWriter struct { ... }
type ReadCloser interface { ... }
...

What did you see instead?

I did not see these functions with receivers (=methods) in the go doc output. go doc cmd does not show methods. It only shows functions with no receivers.

However, if I do go doc io.PipeWriter I see its methods. But I think go doc pkg should be able to lay out all exported API surface of a package (unless it's a deliberate design choice, of course).

@bradfitz bradfitz changed the title cmd/go/doc: does not show methods with receivers cmd/doc: does not show methods with receivers Jan 5, 2017
@bradfitz bradfitz added this to the Go1.9Maybe milestone Jan 5, 2017
@bradfitz
Copy link
Contributor

bradfitz commented Jan 5, 2017

This might be intentional. @robpike?

@rakyll
Copy link
Contributor

rakyll commented Jan 5, 2017

go doc doesn't also show much from interfaces or struct types, e.g. no struct fields are listed. I assume we need to do better in representing them if we list methods for consistency.

@ahmetb
Copy link
Author

ahmetb commented Jan 5, 2017

@rakyll go doc net/http.Server shows the struct fields for me and go doc net.Listener shows the interface contents. go doc os shows the package variables and constants. As far as I can tell, only the receiver methods are missing.

@dsnet
Copy link
Member

dsnet commented Jan 5, 2017

I believe this is intentional.

go doc io is trying to not spam you with every method for every type. I personally think this is reasonable behavior to keep the initial output of go doc io readable. As you've mentioned, if you drill down into go doc io.PipeWriter, it then shows the methods.

@rakyll
Copy link
Contributor

rakyll commented Jan 5, 2017

go doc net/http.Server shows struct fields under net/http.Server not net/http. The methods are more or less similar, strongly related to their types not the package. It is pretty reasonable to avoid them at the package-level summary to avoid spam.

@ahmetb
Copy link
Author

ahmetb commented Jan 5, 2017

What is the purpose of "go doc" vs "godoc"? (Pardon my ignorance as I have no historical context.) Because "godoc" is very verbose and shows everything. Perhaps there can be a "go doc -detailed"?

I am using "go doc" to diff two versions of a package in terms of API changes except the documentation (added methods/types etc). "Godoc" doesn't provide this type of output but "go doc" does, although it is incomplete.

@robpike
Copy link
Contributor

robpike commented Jan 6, 2017

It's intentional. The usual word for "methods with no receivers" in this context is "constructor". Go doc shows the top-level vars, consts, funcs, and types, and constructors for those types. If it printed the docs for every method of every type in the package it would be unusably verbose for many packages.

@robpike robpike closed this as completed Jan 6, 2017
@golang golang locked and limited conversation to collaborators Jan 6, 2018
@rsc rsc unassigned robpike Jun 23, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

6 participants