staticcheck.conf: enable ST1000 to check package docs (#20787)

Fix the small number of existing violations of this check, and enable it for
future runs. The fixes needed were:

 - Clean up a few misspelled package names (probably renames).
 - Clean up a few lexical nits ("Package x" instead of "The x package").
 - Add lint directives to some files affected by build tag variance.
 - Add a missing package comment and re-generate the k8s docs.

The lint overrides are a little ugly, but there are only a few places where we
need them, and it's probably worthwhile to enable the check on the rest of the
repo. Rather than replicate the docs around the build tag, I made the lint
diagnotics reference the "correct" file.

Updates #cleanup

Change-Id: I0d97f2f468542af456a0396cf9a023f04f23e436
Signed-off-by: M. J. Fromberger <fromberger@tailscale.com>

cmd/natc/ippool/ippool.go

@@ -1,7 +1,7 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
-// ippool implements IP address storage, creation, and retrieval for cmd/natc
+// Package ippool implements IP address storage, creation, and retrieval for cmd/natc.
 package ippool
 
 import (

feature/buildfeatures/buildfeatures.go

@@ -3,8 +3,8 @@
 
 //go:generate go run gen.go
 
-// The buildfeatures package contains boolean constants indicating which
+// Package buildfeatures contains boolean constants indicating which features
-// features were included in the binary (via build tags), for use in dead code
+// were included in the binary (via build tags), for use in dead code
-// elimination when using separate build tag protected files is impractical
+// elimination when using separate build tag protected files is impractical or
-// or undesirable.
+// undesirable.
 package buildfeatures

feature/condregister/condregister.go

@@ -1,9 +1,9 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
-// The condregister package registers all conditional features guarded
+// Package condregister registers all conditional features guarded by build
-// by build tags. It is one central package that callers can empty import
+// tags. It is one central package that callers can empty import to ensure all
-// to ensure all conditional features are registered.
+// conditional features are registered.
 package condregister
 
 import (

feature/doctor/doctor.go

@@ -1,7 +1,7 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
-// The doctor package registers the "doctor" problem diagnosis support into the
+// Package doctor registers the "doctor" problem diagnosis support into the
 // rest of Tailscale.
 package doctor
 

feature/featuretags/featuretags.go

@@ -1,7 +1,7 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
-// The featuretags package is a registry of all the ts_omit-able build tags.
+// Package featuretags is a registry of all the ts_omit-able build tags.
 package featuretags
 
 import "tailscale.com/util/set"

k8s-operator/api.md

@@ -6,6 +6,7 @@
 
 ## tailscale.com/v1alpha1
 
+Package v1alpha1 documents the k8s-operator API.
 
 ### Resource Types
 - [Connector](#connector)

k8s-operator/apis/v1alpha1/doc.go

@@ -3,6 +3,7 @@
 
 //go:build !plan9
 
+// Package v1alpha1 documents the k8s-operator API.
 // +kubebuilder:object:generate=true
 // +groupName=tailscale.com
 package v1alpha1

k8s-operator/sessionrecording/ws/conn.go

@@ -3,7 +3,7 @@
 
 //go:build !plan9
 
-// package ws has functionality to parse 'kubectl exec/attach' sessions streamed using
+// Package ws has functionality to parse 'kubectl exec/attach' sessions streamed using
 // WebSocket protocol.
 package ws
 

net/netmon/netmon.go

@@ -1,9 +1,9 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
-// Package monitor provides facilities for monitoring network
+// Package netmon provides facilities for monitoring network interface and
-// interface and route changes. It primarily exists to know when
+// route changes. It primarily exists to know when portable devices move
-// portable devices move between different networks.
+// between different networks.
 package netmon
 
 import (

net/stun/stun.go

@@ -1,7 +1,7 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
-// Package STUN generates STUN request packets and parses response packets.
+// Package stun generates STUN request packets and parses response packets.
 package stun
 
 import (

net/tstun/tun.go

@@ -3,8 +3,8 @@
 
 //go:build !wasm && !tamago && !aix && !solaris && !illumos
 
-// Package tun creates a tuntap device, working around OS-specific
+// Package tstun creates a tuntap device, working around OS-specific quirks if
-// quirks if necessary.
+// necessary.
 package tstun
 
 import (

portlist/portlist.go

@@ -3,8 +3,8 @@
 
 // This file is just the types. The bulk of the code is in poller.go.
 
-// The portlist package contains code that checks what ports are open and
+// Package portlist contains code that checks what ports are open and listening
-// listening on the current machine.
+// on the current machine.
 package portlist
 
 import (

staticcheck.conf

@@ -17,7 +17,7 @@ checks = [
 	# https://github.com/golang/go/wiki/CodeReviewComments, then it
 	# may be an acceptable check.
 
-	# TODO(crawshaw): enable when we have docs? "ST1000", # missing package docs
+	"ST1000", # missing package docs
 	"ST1001", # discourage dot imports
 
 	"QF1004", # Use `strings.ReplaceAll` instead of `strings.Replace` with `n == 1`

tstest/deptest/deptest.go

@@ -1,9 +1,9 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
-// The deptest package contains a shared implementation of negative
+// Package deptest contains a shared implementation of negative dependency
-// dependency tests for other packages, making sure we don't start
+// tests for other packages, making sure we don't start depending on certain
-// depending on certain packages.
+// packages.
 package deptest
 
 import (

tstest/tkatest/tkatest.go

@@ -1,8 +1,8 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
-// tkatest has functions for creating a mock control server that responds
+// Package tkatest has functions for creating a mock control server that
-// to TKA endpoints.
+// responds to TKA endpoints.
 package tkatest
 
 import (

types/appctype/appconnector.go

@@ -1,7 +1,7 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
-// Package appcfg contains an experimental configuration structure for
+// Package appctype contains an experimental configuration structure for
 // "tailscale.com/app-connectors" capmap extensions.
 package appctype
 

util/ctxkey/key.go

@@ -1,7 +1,7 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
-// ctxkey provides type-safe key-value pairs for use with [context.Context].
+// Package ctxkey provides type-safe key-value pairs for use with [context.Context].
 //
 // Example usage:
 //

util/goroutines/goroutines.go

@@ -1,7 +1,7 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
-// The goroutines package contains utilities for tracking and getting active goroutines.
+// Package goroutines contains utilities for tracking and getting active goroutines.
 package goroutines
 
 import (

util/nocasemaps/nocase.go

@@ -1,8 +1,8 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
-// nocasemaps provides efficient functions to set and get entries in Go maps
+// Package nocasemaps provides efficient functions to set and get entries in Go
-// keyed by a string, where the string is always lower-case.
+// maps keyed by a string, where the string is always lower-case.
 package nocasemaps
 
 import (

util/osshare/filesharingstatus_noop.go

@@ -3,6 +3,8 @@
 
 //go:build !windows
 
+//lint:file-ignore ST1000 see filesharingstatus_windows.go
+
 package osshare
 
 import (

util/winutil/authenticode/mksyscall.go

@@ -1,6 +1,8 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
+//lint:file-ignore ST1000 see authenticode_windows.go
+
 package authenticode
 
 //go:generate go run golang.org/x/sys/windows/mkwinsyscall -output zsyscall_windows.go mksyscall.go

util/winutil/gp/mksyscall.go

@@ -1,6 +1,8 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
+//lint:file-ignore ST1000 see gp_windows.go
+
 package gp
 
 //go:generate go run golang.org/x/sys/windows/mkwinsyscall -output zsyscall_windows.go mksyscall.go

util/winutil/s4u/mksyscall.go

@@ -1,6 +1,8 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
+//lint:file-ignore ST1000 see s4u_windows.go
+
 package s4u
 
 //go:generate go run golang.org/x/sys/windows/mkwinsyscall -output zsyscall_windows.go mksyscall.go

util/winutil/winenv/mksyscall.go

@@ -1,6 +1,8 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
+//lint:file-ignore ST1000 see winenv_windows.go
+
 package winenv
 
 //go:generate go run golang.org/x/sys/windows/mkwinsyscall -output zsyscall_windows.go mksyscall.go