cmd/doc: doc links in doc of a method in an interface are not expanded

[dolmen]

What version of Go are you using (go version)?

$ go version
go version go1.20.3 darwin/amd64

What did you do?

package foo

type Foo string

// Bar allows to access [Foo].
type Bar interface {
	// Baz returns a [Foo].
	Baz() Foo
}

What did you expect to see?

$ go doc . Bar
package foo // import "."

type Bar interface {
	// Baz returns a Foo.
	Baz() Foo
}
    Bar allows to access Foo.

What did you see instead?

[Foo] is not expanded in the comment before the Baz method.

$ go doc . Bar
package foo // import "."

type Bar interface {
	// Baz returns a [Foo].
	Baz() Foo
}
    Bar allows to access Foo.

Impact

Doc links are very useful to document packages that rely heavily on interfaces (ex: database/sql/driver) but this issue blocks the full potential of doc links. (also #54033).

[dolmen]

CL 486815 (in which I add godoc links to database/sql and database/sql/driver) is somewhat dependent on this fix as linking from interface method documentation is useful.

[prattmic]

cc @rsc @griesemer

[ianlancetaylor]

This is related to the discussion in #56592. The way that cmd/doc works for aggregate types is that it calls into go/format to print those types. That does the right thing for internal comments. But it does not format doc comments. https://go.dev/cl/483055 applied a workaround to address one aspect of this. Perhaps to really get this right we need to change go/format, or we need to change cmd/doc to not use go/format. Neither seems particularly simple.

[willfaught]

Probably related to, or a dup of, #56004.

[dolmen]

@willfaught #56004 mentions a struct type while here this is an interface type. Both are related (Ian mentioned "aggregate" types above) but not strictly the same, so not dup.

[gopherbot]

Change https://go.dev/cl/501115 mentions this issue: context: add godoc links