proposal: go/doc: inline type alias documentation

[carnott-snap]

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)

[DeedleFake]

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]

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]

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]

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]

@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]

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

[rsc]

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