x/pkgsite: doc links used for identifiers without anchors/headings

[bitlux]

What is the URL of the page with the issue?

https://pkg.go.dev/net/http#:~:text=%5BTransport.TLSNextProto%5D%20(for%20clients)%20or%20%5BServer.TLSNextProto%5D

What is your user agent?

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36

Screenshot

What is the problem?

Code authors attempt to use doc links to link to members of structs or interfaces. Pkgsite does not generate anchors for those identifiers, so there is nothing to link to, and the doc link appears as [Transport.TLSNextProto].

This issue is widespread throughout the standard library, but net/http seems to have the most occurrences.

The options that I see are:

1. Remove the extraneous [] from net/http/server.go and other files

2. Update pkgsite to create anchors for members of structs and interfaces. https://tip.golang.org/doc/comment#doclinks says that doc links "refer to exported identifiers"; is an exported member of an exported type an "exported identifier"? If so, that seems to suggest there should be anchors for those identifiers.

3. Do nothing.

If a consensus is reached that option 2 is best, I would like to request that I be able to make the first attempt at modifying pkgsite.

[gabyhelp]

Related Issues

• x/pkgsite: [Doc links] Cannot refer to types but Go Doc stated it could #67473 (closed)
• x/pkgsite: doc links in interface and struct function comments are not linked #73327
• x/pkgsite: documentation feedback - tracking issue #37819 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[bitlux]

This is not a dupe of #56004. #56004 is about using doc links in a comment inside a struct or interface definition. Any type of doc link in such a comment does not work, regardless of what it links to.

This issue is about doc links to members of structs or interfaces, regardless of where in the source file they appear.

(This issue is a dupe of #67473, which is also incorrectly duped to #56004).

[bitlux]

@seankhliao, please reconsider based on my comment above. (I cannot yet rule out that both this/#67473 and #56004 have the same cause, but I have not seen any analysis suggesting that this is the case. They certainly manifest in different ways.)