golang/gddo

GoDoc does not detected exported methods of un-exported structs?

Closed this issue · 3 comments

akamensky commented

I have written a library, and I believe I written rather detailed documentation for it. However from all documentation only a couple of methods shows up on GoDoc page

My code follows what I know as a good practice for doing something in Go. Namely - when user should not instantiate any struct on their own I do not export the named struct, but I provide a method func NewSomething(args...) *something that will return pointer to the instance of the struct and thus users will have an access to the exported methods of that struct.

However GoDoc seems to disagree with this and does not show those methods even though they are exported. Which I am not sure a bug or a design choice. But I believe this should not be the case as I think anything exported will be potentially accessibly by user and thus requires documentation.

dmitshur commented

godoc.org displays documentation for Go packages that aren't just in standard library, but aside from that, its behavior is based directly on cmd/go (https://golang.org/pkg/). Changes to cmd/go behavior should be discussed in the Go issue tracker.

This is an issue that has come up in the past, and the general consensus seems to be that returning unexported types is not a good practice, because it's hard for callers to use unexported types. golint warns about this pattern with "exported func NewSample returns unexported type *main.sample, which can be annoying to use". A better solution is to return an exported interface that the type implements, or make the type exported.

See previous discussions at:

  • 👍1
akamensky commented

@shurcooL Thanks for clarification. After reading the links you provided I feel that Go's developers made a terrible choice and people keep providing them with valid arguments, but those arguments are always ignored.

Anyway, thanks for pointing out that this is not a GoDoc's fault. I will prefer to keep my implementation as-is just because it is a common sense (common sense that only what needs to be used directly should be exported and all internal stuff should not be exported even if user gets a pointer to it for like 5 seconds).

I guess it is okay to close this one as a dup or wontfix.

dmitshur commented

Ok, I'll close, since there's nothing actionable we can do in this repository.

if user gets a pointer to it for like 5 seconds

I would suggest keeping an open mind when it comes to Go best practices. Users of a package that returns an unexported type won't be able to pass it to a helper function, or store the value as a field in a struct, etc.

If you want to discuss this further or learn more about the topic, the best place to do so would be one of these forums.