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

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

Open
jimmyfrasche opened this issue Apr 19, 2014 · 5 comments
Open

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

jimmyfrasche opened this issue Apr 19, 2014 · 5 comments
Milestone

Comments

@jimmyfrasche
Copy link
Member

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
Copy link
Contributor

Comment 1:

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

@adonovan
Copy link
Member

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
Copy link
Member Author

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
Copy link

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.

@bradfitz bradfitz removed the new label Dec 18, 2014
@rsc rsc added this to the Unplanned milestone Apr 10, 2015
@rsc rsc removed the release-none label Apr 10, 2015
@rsc rsc changed the title godoc: conditionally expose unexported types x/tools/cmd/godoc: conditionally expose unexported types Apr 14, 2015
@rsc rsc removed the repo-tools label Apr 14, 2015
@jimmyfrasche
Copy link
Member Author

#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.

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

No branches or pull requests

6 participants