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

Jump to bottom

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

Open
dolmen opened this issue Apr 20, 2023 · 6 comments
Open

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

dolmen opened this issue Apr 20, 2023 · 6 comments
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone
Backlog

Comments

@dolmen
Copy link
Contributor

dolmen commented Apr 20, 2023 •
edited

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

dolmen commented Apr 20, 2023

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 prattmic added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Apr 21, 2023
@prattmic prattmic added this to the Backlog milestone Apr 21, 2023
@prattmic
Copy link
Member

cc @rsc @griesemer

@ianlancetaylor
Copy link
Contributor

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

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

@ianlancetaylor ianlancetaylor mentioned this issue Apr 21, 2023
Open
@dolmen
Copy link
Contributor Author

dolmen commented Apr 24, 2023

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

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

gopherbot pushed a commit that referenced this issue Jun 6, 2023
@dolmen @gopherbot
context: add godoc links
1c89de6 
This clarifies the ambiguity of the TODO word as raised in
#56625.
Also links the introduction text to each function.

Note: linking from Context methods documentation is blocked for now by
#59728.

Change-Id: Ie6080bd8dee3a652436b0875ddc5f452287c9493
Reviewed-on: https://go-review.googlesource.com/c/go/+/501115
Reviewed-by: Ian Lance Taylor <iant@google.com>
Reviewed-by: David Chase <drchase@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
Run-TryBot: Ian Lance Taylor <iant@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Milestone
Backlog
Development

No branches or pull requests
5 participants
@willfaught @dolmen @prattmic @ianlancetaylor @gopherbot