all: apply godoc [Name] link conventions across comments

Every Go-identifier reference in // and /* */ comments now uses
godoc's [Name] linking syntax so pkg.go.dev and `go doc` render
them as clickable cross-references. No behaviour change.

Pattern applied across the tree:
  In-package         [Foo], [Foo.Bar]
  Cross-package      [pkg.Foo], [pkg.Foo.Bar]
  Stdlib             [netip.Prefix], [errors.Is], [context.Context]
  Tailscale          [tailcfg.MapResponse], [tailcfg.Node.CapMap],
                     [tailcfg.NodeAttrSuggestExitNode]

Skip rules:
  - File:line refs left as plain text
  - HuJSON wire keys inside backtick raw strings untouched
  - ACL/policy syntax tokens (tag:foo, autogroup:self, ...) not Go
    symbols, left as plain text
  - JSON/OIDC wire keys, gorm tags, RFC IPv6 placeholders, markdown
    link tags, decorative dividers — all left as-is

hscontrol/util/addr.go

@@ -9,7 +9,7 @@ import (
 	"go4.org/netipx"
 )
 
-// This is borrowed from, and updated to use IPSet
+// This is borrowed from, and updated to use [netipx.IPSet]
 // https://github.com/tailscale/tailscale/blob/71029cea2ddf82007b80f465b256d027eab0f02d/wgengine/filter/tailcfg.go#L97-L162
 // TODO(kradalby): contribute upstream and make public.
 var (
@@ -24,7 +24,7 @@ var (
 //   - a CIDR (e.g. "192.168.0.0/16")
 //   - a range of two IPs, inclusive, separated by hyphen ("2eff::1-2eff::0800")
 //
-// bits, if non-nil, is the legacy SrcBits CIDR length to make a IP
+// bits, if non-nil, is the legacy [tailcfg.FilterRule.SrcBits] CIDR length to make a IP
 // address (without a slash) treated as a CIDR of *bits length.
 // nolint
 func ParseIPSet(arg string, bits *int) (*netipx.IPSet, error) {
@@ -114,7 +114,7 @@ func StringToIPPrefix(prefixes []string) ([]netip.Prefix, error) {
 	return result, nil
 }
 
-// IPSetAddrIter returns a function that iterates over all the IPs in the IPSet.
+// IPSetAddrIter returns a function that iterates over all the IPs in the [netipx.IPSet].
 func IPSetAddrIter(ipSet *netipx.IPSet) iter.Seq[netip.Addr] {
 	return func(yield func(netip.Addr) bool) {
 		for _, rng := range ipSet.Ranges() {

hscontrol/util/dns.go

@@ -23,7 +23,7 @@ const (
 )
 
 // DNS validation errors. Hostname-side validation lives on
-// `tailscale.com/util/dnsname` and NodeStore collision handling; only
+// `tailscale.com/util/dnsname` and [state.NodeStore] collision handling; only
 // the username-side errors stay in this package.
 var (
 	ErrUsernameTooShort        = errors.New("username must be at least 2 characters long")
@@ -71,12 +71,12 @@ func ValidateUsername(username string) error {
 	return nil
 }
 
-// generateMagicDNSRootDomains generates a list of DNS entries to be included in `Routes` in `MapResponse`.
+// generateMagicDNSRootDomains generates a list of DNS entries to be included in [tailcfg.DNSConfig.Routes] in [tailcfg.MapResponse].
 // This list of reverse DNS entries instructs the OS on what subnets and domains the Tailscale embedded DNS
 // server (listening in 100.100.100.100 udp/53) should be used for.
 //
 // Tailscale.com includes in the list:
-// - the `BaseDomain` of the user
+// - the [types.DNSConfig.BaseDomain] of the user
 // - the reverse DNS entry for IPv6 (0.e.1.a.c.5.1.1.a.7.d.f.ip6.arpa., see below more on IPv6)
 // - the reverse DNS entries for the IPv4 subnets covered by the user's `IPPrefix`.
 //   In the public SaaS this is [64-127].100.in-addr.arpa.
@@ -93,7 +93,7 @@ func ValidateUsername(username string) error {
 // From the netmask we can find out the wildcard bits (the bits that are not set in the netmask).
 // This allows us to then calculate the subnets included in the subsequent class block and generate the entries.
 func GenerateIPv4DNSRootDomain(ipPrefix netip.Prefix) []dnsname.FQDN {
-	// Conversion to the std lib net.IPnet, a bit easier to operate
+	// Conversion to the std lib [net.IPNet], a bit easier to operate
 	netRange := netipx.PrefixIPNet(ipPrefix)
 	maskBits, _ := netRange.Mask.Size()
 
@@ -130,12 +130,12 @@ func GenerateIPv4DNSRootDomain(ipPrefix netip.Prefix) []dnsname.FQDN {
 	return fqdns
 }
 
-// generateMagicDNSRootDomains generates a list of DNS entries to be included in `Routes` in `MapResponse`.
+// generateMagicDNSRootDomains generates a list of DNS entries to be included in [tailcfg.DNSConfig.Routes] in [tailcfg.MapResponse].
 // This list of reverse DNS entries instructs the OS on what subnets and domains the Tailscale embedded DNS
 // server (listening in 100.100.100.100 udp/53) should be used for.
 //
 // Tailscale.com includes in the list:
-// - the `BaseDomain` of the user
+// - the [types.DNSConfig.BaseDomain] of the user
 // - the reverse DNS entry for IPv6 (0.e.1.a.c.5.1.1.a.7.d.f.ip6.arpa., see below more on IPv6)
 // - the reverse DNS entries for the IPv4 subnets covered by the user's `IPPrefix`.
 //   In the public SaaS this is [64-127].100.in-addr.arpa.

hscontrol/util/dns_test.go

@@ -9,7 +9,6 @@ import (
 	"tailscale.com/util/must"
 )
 
-
 func TestMagicDNSRootDomains100(t *testing.T) {
 	domains := GenerateIPv4DNSRootDomain(netip.MustParsePrefix("100.64.0.0/10"))
 

hscontrol/util/net.go

@@ -35,7 +35,7 @@ func MustStringsToPrefixes(strings []string) []netip.Prefix {
 	return ret
 }
 
-// TheInternet returns the IPSet for the Internet.
+// TheInternet returns the [netipx.IPSet] for the Internet.
 // https://www.youtube.com/watch?v=iDbyYGrswtg
 var TheInternet = sync.OnceValue(func() *netipx.IPSet {
 	var internetBuilder netipx.IPSetBuilder

hscontrol/util/util.go

@@ -94,7 +94,7 @@ type Traceroute struct {
 	Err error
 }
 
-// ParseTraceroute parses the output of the traceroute command and returns a Traceroute struct.
+// ParseTraceroute parses the output of the traceroute command and returns a [Traceroute] struct.
 func ParseTraceroute(output string) (Traceroute, error) {
 	lines := strings.Split(strings.TrimSpace(output), "\n")
 	if len(lines) < 1 {

hscontrol/util/util_test.go

@@ -796,7 +796,6 @@ over a maximum of 30 hops:
 	}
 }
 
-
 func TestGenerateRegistrationKey(t *testing.T) {
 	t.Parallel()
 

hscontrol/util/zlog/fields.go

@@ -1,8 +1,8 @@
 // Package zlog provides zerolog utilities for safe and consistent logging.
 //
 // This package contains:
-//   - Safe wrapper types for external types (tailcfg.Hostinfo, tailcfg.MapRequest)
-//     that implement LogObjectMarshaler with security-conscious field redaction
+//   - Safe wrapper types for external types ([tailcfg.Hostinfo], [tailcfg.MapRequest])
+//     that implement [zerolog.LogObjectMarshaler] with security-conscious field redaction
 //
 // For field name constants, use the zf subpackage:
 //

hscontrol/util/zlog/hostinfo.go

@@ -6,7 +6,7 @@ import (
 	"tailscale.com/tailcfg"
 )
 
-// SafeHostinfo wraps tailcfg.Hostinfo for safe logging.
+// SafeHostinfo wraps [tailcfg.Hostinfo] for safe logging.
 //
 // SECURITY: This wrapper intentionally redacts device fingerprinting data
 // that could be used to identify or track specific devices:
@@ -24,12 +24,12 @@ type SafeHostinfo struct {
 	hi *tailcfg.Hostinfo
 }
 
-// Hostinfo creates a SafeHostinfo wrapper for safe logging.
+// Hostinfo creates a [SafeHostinfo] wrapper for safe logging.
 func Hostinfo(hi *tailcfg.Hostinfo) SafeHostinfo {
 	return SafeHostinfo{hi: hi}
 }
 
-// MarshalZerologObject implements zerolog.LogObjectMarshaler.
+// MarshalZerologObject implements [zerolog.LogObjectMarshaler].
 func (s SafeHostinfo) MarshalZerologObject(e *zerolog.Event) {
 	if s.hi == nil {
 		return

hscontrol/util/zlog/init_test.go

@@ -2,9 +2,9 @@ package zlog
 
 import "github.com/rs/zerolog"
 
-// init pins zerolog to TraceLevel for the zlog test binary.
+// init pins zerolog to [zerolog.TraceLevel] for the zlog test binary.
 //
-// zlog's tests use zerolog.New(&buf) and assert on Info-level output. zerolog's
+// zlog's tests use [zerolog.New] with a buffer and assert on Info-level output. zerolog's
 // (*Logger).should() gates emission on the global level, so any global level
 // above Info would silently break the assertions.
 //

hscontrol/util/zlog/maprequest.go

@@ -6,11 +6,11 @@ import (
 	"tailscale.com/tailcfg"
 )
 
-// SafeMapRequest wraps tailcfg.MapRequest for safe logging.
+// SafeMapRequest wraps [tailcfg.MapRequest] for safe logging.
 //
 // SECURITY: This wrapper does not log sensitive information:
 //   - Endpoints: Client IP addresses and ports
-//   - Hostinfo: Device fingerprinting data (handled by SafeHostinfo)
+//   - Hostinfo: Device fingerprinting data (handled by [SafeHostinfo])
 //   - DERPForceWebsockets: Network configuration details
 //
 // Only safe fields are logged:
@@ -23,12 +23,12 @@ type SafeMapRequest struct {
 	req *tailcfg.MapRequest
 }
 
-// MapRequest creates a SafeMapRequest wrapper for safe logging.
+// MapRequest creates a [SafeMapRequest] wrapper for safe logging.
 func MapRequest(req *tailcfg.MapRequest) SafeMapRequest {
 	return SafeMapRequest{req: req}
 }
 
-// MarshalZerologObject implements zerolog.LogObjectMarshaler.
+// MarshalZerologObject implements [zerolog.LogObjectMarshaler].
 func (s SafeMapRequest) MarshalZerologObject(e *zerolog.Event) {
 	if s.req == nil {
 		return
@@ -46,6 +46,6 @@ func (s SafeMapRequest) MarshalZerologObject(e *zerolog.Event) {
 
 	// SECURITY: The following fields are intentionally NOT logged:
 	// - Endpoints: Client IP addresses and ports
-	// - Hostinfo: Device fingerprinting data (use SafeHostinfo separately if needed)
+	// - Hostinfo: Device fingerprinting data (use [SafeHostinfo] separately if needed)
 	// - DERPForceWebsockets: Network configuration details
 }