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

proposal: go/doc: inline type alias documentation #44905

Closed
carnott-snap opened this issue Mar 10, 2021 · 7 comments
Closed

proposal: go/doc: inline type alias documentation #44905

carnott-snap opened this issue Mar 10, 2021 · 7 comments

Comments

@carnott-snap
Copy link

I would like type aliases to be inlined for better readability. Consider a package with an extensive experimental API. Users would have to navigate back and forth between two (or more) packages: one containing the symbols they are allowed to access, and another one (or more) containing the usage documentation, struct fields, interface methods, etc. And where one experimental function accepts an experimental struct as a parameter:

package internal

type MyInterface interface {
  MyFunc(MyStruct) error
}

type MyStruct struct {
  ...
}
package experimental

type MyInterface = internal.MyInterface
type MyStruct = internal.MyStruct

When reading the documentation for internal.MyInterface.MyFunc, you see MyStruct. There is no back-reference to experimental.MyStruct. So you just have to hope the API designers are sane and didn't instead do:

package experimental
type FooBar = internal.MyStruct

Originally posted by @dfawley in #34409 (comment)

@smasher164 smasher164 changed the title godoc alias inlining go/doc: inline type alias documentation Mar 11, 2021
@smasher164 smasher164 changed the title go/doc: inline type alias documentation proposal: go/doc: inline type alias documentation Mar 11, 2021
@gopherbot gopherbot added this to the Proposal milestone Mar 11, 2021
@DeedleFake
Copy link

This would be useful for using ent. It uses a lot of code generation and includes aliases for several things in one of their own packages inside of the main generated package to make the usage easier, but the documentation winds up with things like

type Value = ent.Value
    ent aliases to avoid import conflicts in user's code.

It's not particularly helpful, and getting the documentation for the aliased type can be a bit awkward because the generated package is also usually called ent, and thus the go doc command needs a more of the path to disambiguate:

  • go doc ent.value gets the above.
  • go doc entgo.io/ent.value gets the original type's documentation.

@rsc
Copy link
Contributor

rsc commented Apr 7, 2021

It's not clear this is a win always. Especially for aliases to non-internal packages.
But even in aliases to internal packages, inlining has to be careful to qualify names.
Like if you have

package internal

type T struct { X U }
type U int

package p

import "internal"

type T = internal.T

you cannot change that to

type T struct { X U }

because there is no U in p.

Until now it has basically been the rule that if you need to do an alias to an internal type then you document everything in the package with the alias, because that's what users are looking at.

@rsc
Copy link
Contributor

rsc commented Apr 7, 2021

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

@urandom2
Copy link
Contributor

urandom2 commented Apr 7, 2021

It's not clear this is a win always. Especially for aliases to non-internal packages.

Maybe there should be a way to signal to godoc that you want it inlined?

But even in aliases to internal packages, inlining has to be careful to qualify names.

This is not really a webui problem since pkgsite/godoc can link against internal.U.

For the cli, we already have the problem that import pkg "path/to/package" makes symbols show up as pkg.U, and frequently I cannot find things when that happens; so this does not seem like a regression.

We can also add a comment to clarify what is going on, similar to // Deprecated: reason:

// T is exported.
//
// Alias: of internal.T.
type T struct { X U }

Originally:
// T is exported.
type T = internal.T

Alternatives include partially qualifying the references:

// T is exported.
type T struct { X internal.U }

However this is confusing, imo, and propagates pkg issue above.

Until now it has basically been the rule that if you need to do an alias to an internal type then you document everything in the package with the alias, because that's what users are looking at.

This makes it really hard to see struct fields and implemented methods.

@rsc
Copy link
Contributor

rsc commented Apr 14, 2021

@griesemer also points out that we do not even have dependency type information in 'go doc' today.

We probably shouldn't make 'go doc' depend on doing that either, which would make it slower and potentially break sometimes.

@rsc
Copy link
Contributor

rsc commented Apr 21, 2021

Based on the discussion above, this proposal seems like a likely decline.
— rsc for the proposal review group

@rsc
Copy link
Contributor

rsc commented Apr 28, 2021

No change in consensus, so declined.
— rsc for the proposal review group

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