golang/go

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

dolmen opened this issue · 6 comments

dolmen commented

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 commented

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.

ianlancetaylor commented

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 commented

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