x/tools/cmd/godoc: conditionally expose unexported types

[jimmyfrasche]

Currently godoc only exposes the documentation of exported types, vars, etc.

However, there are a number of cases where it would be convenient to expose unexported
types: when there is a variable or constant of that type and when a function or method
takes or returns values of that type.

If the unexported type has exported methods, this allows them to be shown in godoc. It
is less important if it does not, but it would still allow godoc to render a link to
that type, showing its docs, consts, and vars.

The same effect, of course, can be generated by exporting the type, but leaving it
unexported, if nothing else, is a signal that users should not create arbitrary values
of this type, which has to be manually documented if you export the type.

This is related, conceptually and likely implementation-wise, to issue #5860, issue #5397
and its duplicate (that contains more information) issue #7815

[ianlancetaylor]

Comment 1:

Labels changed: added repo-tools, release-none.

[adonovan]

Comment 2:

I assume you're talking about the web interface, in which case appending ?m=all to the
URL should do what you want.
There is no equivalent to this on the command-line interface (as noted by issue #8093).

[jimmyfrasche]

Comment 3:

No. I want it to expose just those private types that can be reached by the public api,
not all of them.

[gopherbot]

Comment 4 by nickcarenza:

I thought I would provide an example of where this would be useful:
type obj struct {
    RequiredProperty someType
}
func NewObj (p someType) *obj {
    return &obj {
        RequiredProperty p
    }
}
func (o *obj) ExportedMethod ( ) {
    // ...
    return ...
}
In this example, I want objects of type obj to only be created using the exported NewObj
method. NewObj has exported properties and methods that (I feel) the documentation
should show by default.

[jimmyfrasche]

#16043 got me thinking about this again, and I think I can better present my earlier thoughts:

Exported v. unexported is an important distinction, but unexported elements can legally be part of the API of a package, directly or indirectly.

I think there needs to be a notion of "accessible" elements in a package.

This includes all exported elements as well as the subset of the unexported such that:

• it's the type of an exported var or const
• it's the type of an accessible field
• it's the type of a parameter or return of an accessible func or method
• they're embedded in an accessible type and have accessible methods and fields
• it's any of the exported methods and fields of an accessible type

I've created a repo containing these cases: https://github.com/jimmyfrasche/inaccessible2godoc

You can see these with ?m=all but you also see everything unexported that is not accessible by the above definition, which adds noise when all you wanted to know was the public API not the internals.

I don't know if this concept needs to be in the language spec (unless it adds clarity, of course).

But a general mechanism for computing the set of accessible items could be added to go/types or a package in x/.

godoc could use that to filter instead of ast.IsExported to get the complete API for a package. There wouldn't need to be any special handling of fields and methods from embedded but unexported types, just a link to the unexported but accessible type as there would be were the type exported.

golint likewise could chastise "unexported X is accessible and should be documented".

I'm sure there are other uses.