https://go.dev/doc/comment#doclinks currently says:
Doc links are links of the form “[Name1]” or “[Name1.Name2]” to refer to exported identifiers in the current package
but it is somewhat ambiguous about whether the [Name1.Name2] form can refer to struct fields or only methods.
In practice, people do seem to intuitively expect references to struct fields to work; for example, this comment on types.Package.GoVersion (written by @rsc) refers to the go/ast.File.GoVersion struct field, and pkg.go.dev appears to render that reference correctly:
However, similar references within the same package are not rendered as links. For example, the reference to [CheckedFiles.SizeError] from zip.CheckedFiles.Err is currently rendered as plain text:
go/doc.Parser uses different functions to resolve intra- vs. inter-package references: it appears that the LookupPackage hook being used by pkgsite does resolve struct fields, whereas the LookupSym hook does not.
Comment From: bcmills
I think the bug is in go/doc. Although the Package.syms field lacks a clarifying comment, in practice it appears not to include struct fields:
https://cs.opensource.google/go/go/+/refs/heads/master:src/go/doc/doc.go;l=159-171;drc=fe5af1532ab9c749d880c05e0ffe0e17bf874d7f
Comment From: gopherbot
Change https://go.dev/cl/510315 mentions this issue: go/doc: recognize intra-package struct field references
Comment From: gopherbot
Change https://go.dev/cl/528402 mentions this issue: go/doc: add a golden test that reproduces #62640
Comment From: bcmills
This is blocked awaiting code review, so moving to Backlog.
Comment From: artyom
I was about to file an issue for net/http.Transport documentation rendering and then I found this issue.
¶ go doc http.Transport | grep -A3 'Transport caches'
By default, Transport caches connections for future re-use. This may
leave many open connections when accessing many hosts. This behavior
can be managed using Transport.CloseIdleConnections method and the
[Transport.MaxIdleConnsPerHost] and [Transport.DisableKeepAlives] fields.
Hope https://go.dev/cl/510315 gets some attention soon.
Comment From: stevenh
I would love to see this hit 1.23 is there any chance of that @bcmills and is there anything I can do to help make that happen?
Comment From: bcmills
I'm no longer on the Go team so there's zero chance of my CL landing as-is — but you're welcome to clone it and shepherd it through the review process! 🙃
Comment From: cespare
This is quite a visible issue with rendered package docs. There are about 30 instances where it occurs in the net/http documentation alone.
@griesemer and @golang/pkgsite -- can you suggest a good person to own this?
Comment From: FiloSottile
@griesemer and @golang/pkgsite, friendly ping on this, we have more and more struct field links in various docs that show up as broken links, and it keeps getting reported.
Comment From: jba
@FiloSottile Thanks for the bump. I've assigned this to myself and will take a look at it when I have some breathing room in my schedule.
Comment From: gopherbot
Change https://go.dev/cl/681235 mentions this issue: go/doc: add a golden test that reproduces #62640