x/pkgsite: [Doc links] Cannot refer to types but Go Doc stated it could

[Z3NTL3]

What is the URL of the page with the issue?

https://go.dev/doc/comment#links

What is your user agent?

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36

Screenshot

What did you do?

// Client for both HTTP and HTTPS proxy
//
// Implements HTTP FORWARD and HTTP TUNNEL mechanism.
type HTTPClient struct {
	Auth // Authentication
	TLS bool // TLS
}

type Conn = net.Conn

// # Doc
//
// Tunnels through given proxy, for HTTPS you should 
// set [HTTPClient.TLS] to true, which will perform HTTP TUNNEL rather than HTTP Forward. 
// Defaults to false which is HTTP proxy aka HTTP FORWARD.
//
// Only HTTP TUNNEL (HTTPS) allows arbitrary data after initial handshake.
//
// # Example
//
// See ``tests`` directory for more examples.
//
// # Reference
//
// [HTTP proxy (HTTP FORWARD)]: https://en.wikipedia.org/wiki/Proxy_server#Implementations_of_proxies
// [HTTPS proxy (HTTP TUNNEL)]: https://en.wikipedia.org/wiki/HTTP_tunnel#HTTP_CONNECT_method
func (c *HTTPClient) PROXY(url string, proxy Context, timeout time.Duration) (conn Conn, err error)

Note

Please note that I have formatted it usinggofmt

What did you see happen?

It did not turn [HTTPClient.TLS] to hyper referenceable text (blue) .

What did you expect to see?

The Go Doc Comments website clearly states that this is valid, as of the following statement:

Doc links are links of the form “[Name1]” or “[Name1.Name2]” to refer to exported identifiers in the current package, or “[pkg]”, “[pkg.Name1]”, or “[pkg.Name1.Name2]” to refer to identifiers in other packages.
Source

Additionally

As an addition to the previous problem, I did found something different much stranger.

// # Reference
//
// [HTTP proxy (HTTP FORWARD)]: https://en.wikipedia.org/wiki/Proxy_server#Implementations_of_proxies
// [HTTPS proxy (HTTP TUNNEL)]: https://en.wikipedia.org/wiki/HTTP_tunnel#HTTP_CONNECT_method

This seems not to show anything at all but according to Go Doc this is valid!

"A span of unindented non-blank lines defines link targets when every line is of the form “[Text]: URL”. In other text in the same doc comment, “[Text]” represents a link to URL using the given text—in HTML, Text. For example:"
Source

[fzipp]

Re your second part: you have to use the links, not just declare them, e.g.

// # Reference
//
// Bla bla bla [HTTP proxy (HTTP FORWARD)] bla bla bla [HTTPS proxy (HTTP TUNNEL)] bla bla.
//
// [HTTP proxy (HTTP FORWARD)]: https://en.wikipedia.org/wiki/Proxy_server#Implementations_of_proxies
// [HTTPS proxy (HTTP TUNNEL)]: https://en.wikipedia.org/wiki/HTTP_tunnel#HTTP_CONNECT_method

[Z3NTL3]

Ye the second part was a misread. Looking forward for the solve for the first part.

Re your second part: you have to use the links, not just declare them, e.g.

// # Reference
//
// Bla bla bla [HTTP proxy (HTTP FORWARD)] bla bla bla [HTTPS proxy (HTTP TUNNEL)] bla bla.
//
// [HTTP proxy (HTTP FORWARD)]: https://en.wikipedia.org/wiki/Proxy_server#Implementations_of_proxies
// [HTTPS proxy (HTTP TUNNEL)]: https://en.wikipedia.org/wiki/HTTP_tunnel#HTTP_CONNECT_method

Hey! Yes, thanks. The second part was a misread. Looking forward for a solve for the first part.

[seankhliao]

Duplicate of #56004