all: add test for package comments, fix, add comments as needed

Updates #cleanup

Change-Id: Ic4304e909d2131a95a38b26911f49e7b1729aaef
Signed-off-by: Brad Fitzpatrick <bradfitz@tailscale.com>

appc/appctest/appctest.go

@@ -1,6 +1,7 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
+// Package appctest contains code to help test App Connectors.
 package appctest
 
 import (

cmd/cloner/clonerex/clonerex.go

@@ -3,6 +3,7 @@
 
 //go:generate go run tailscale.com/cmd/cloner  -clonefunc=true -type SliceContainer
 
+// Package clonerex is an example package for the cloner tool.
 package clonerex
 
 type SliceContainer struct {

cmd/k8s-operator/dnsrecords.go

@@ -3,9 +3,6 @@
 
 //go:build !plan9
 
-// tailscale-operator provides a way to expose services running in a Kubernetes
-// cluster to your Tailnet and to make Tailscale nodes available to cluster
-// workloads
 package main
 
 import (

cmd/k8s-operator/generate/main.go

@@ -3,6 +3,7 @@
 
 //go:build !plan9
 
+// The generate command creates tailscale.com CRDs.
 package main
 
 import (

cmd/tailscale/cli/ffcomplete/internal/complete.go

@@ -1,6 +1,7 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
+// Package internal contains internal code for the ffcomplete package.
 package internal
 
 import (

cmd/xdpderper/xdpderper.go

@@ -1,6 +1,7 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
+// Command xdpderper runs the XDP STUN server.
 package main
 
 import (

derp/xdp/headers/update.go

@@ -1,6 +1,8 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
+// The update program fetches the libbpf headers from the libbpf GitHub repository
+// and writes them to disk.
 package main
 
 import (

derp/xdp/xdp.go

@@ -1,6 +1,7 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
+// Package xdp contains the XDP STUN program.
 package xdp
 
 // XDPAttachFlags represents how XDP program will be attached to interface. This

go.mod

@@ -20,7 +20,6 @@ require (
 	github.com/coreos/go-systemd v0.0.0-20191104093116-d3cd4ed1dbcf
 	github.com/creack/pty v1.1.21
 	github.com/dave/courtney v0.4.0
-	github.com/dave/jennifer v1.7.0
 	github.com/dave/patsy v0.0.0-20210517141501-957256f50cba
 	github.com/dblohm7/wingoes v0.0.0-20240119213807-a09d6be7affa
 	github.com/digitalocean/go-smbios v0.0.0-20180907143718-390a4f403a8e
@@ -44,7 +43,6 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/goreleaser/nfpm/v2 v2.33.1
 	github.com/hdevalence/ed25519consensus v0.2.0
-	github.com/iancoleman/strcase v0.3.0
 	github.com/illarion/gonotify v1.0.1
 	github.com/inetaf/tcpproxy v0.0.0-20240214030015-3ce58045626c
 	github.com/insomniacslk/dhcp v0.0.0-20231206064809-8c70d406f6d2

go.sum

@@ -242,8 +242,6 @@ github.com/dave/brenda v1.1.0 h1:Sl1LlwXnbw7xMhq3y2x11McFu43AjDcwkllxxgZ3EZw=
 github.com/dave/brenda v1.1.0/go.mod h1:4wCUr6gSlu5/1Tk7akE5X7UorwiQ8Rij0SKH3/BGMOM=
 github.com/dave/courtney v0.4.0 h1:Vb8hi+k3O0h5++BR96FIcX0x3NovRbnhGd/dRr8inBk=
 github.com/dave/courtney v0.4.0/go.mod h1:3WSU3yaloZXYAxRuWt8oRyVb9SaRiMBt5Kz/2J227tM=
-github.com/dave/jennifer v1.7.0 h1:uRbSBH9UTS64yXbh4FrMHfgfY762RD+C7bUPKODpSJE=
-github.com/dave/jennifer v1.7.0/go.mod h1:nXbxhEmQfOZhWml3D1cDK5M1FLnMSozpbFN/m3RmGZc=
 github.com/dave/patsy v0.0.0-20210517141501-957256f50cba h1:1o36L4EKbZzazMk8iGC4kXpVnZ6TPxR2mZ9qVKjNNAs=
 github.com/dave/patsy v0.0.0-20210517141501-957256f50cba/go.mod h1:qfR88CgEGLoiqDaE+xxDCi5QA5v4vUoW0UCX2Nd5Tlc=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -548,8 +546,6 @@ github.com/huandu/xstrings v1.4.0 h1:D17IlohoQq4UcpqD7fDk80P7l+lwAmlFaBHgOipl2FU
 github.com/huandu/xstrings v1.4.0/go.mod h1:y5/lhBue+AyNmUVz9RLU9xbLR0o4KIIExikq4ovT0aE=
 github.com/hugelgupf/vmtest v0.0.0-20240102225328-693afabdd27f h1:ov45/OzrJG8EKbGjn7jJZQJTN7Z1t73sFYNIRd64YlI=
 github.com/hugelgupf/vmtest v0.0.0-20240102225328-693afabdd27f/go.mod h1:JoDrYMZpDPYo6uH9/f6Peqms3zNNWT2XiGgioMOIGuI=
-github.com/iancoleman/strcase v0.3.0 h1:nTXanmYxhfFAMjZL34Ov6gkzEsSJZ5DbhxWjvSASxEI=
-github.com/iancoleman/strcase v0.3.0/go.mod h1:iwCmte+B7n89clKwxIoIXy/HfoL7AsD47ZCWhYzw7ho=
 github.com/ianlancetaylor/demangle v0.0.0-20181102032728-5e5cf60278f6/go.mod h1:aSSvb/t6k1mPoxDqO4vJh6VOCGPwU4O0C2/Eqndh1Sc=
 github.com/ianlancetaylor/demangle v0.0.0-20200824232613-28f6c0f3b639/go.mod h1:aSSvb/t6k1mPoxDqO4vJh6VOCGPwU4O0C2/Eqndh1Sc=
 github.com/illarion/gonotify v1.0.1 h1:F1d+0Fgbq/sDWjj/r66ekjDG+IDeecQKUFH4wNwsoio=

internal/tooldeps/tooldeps.go

@@ -3,6 +3,8 @@
 
 //go:build for_go_mod_tidy_only
 
+// Package tooldeps contains dependencies for tools used in the Tailscale repository,
+// so they're not removed by "go mod tidy".
 package tooldeps
 
 import (

ipn/ipnlocal/local.go

@@ -1,6 +1,8 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
+// Package ipnlocal is the heart of the Tailscale node agent that controls
+// all the other misc pieces of the Tailscale node.
 package ipnlocal
 
 import (

ipn/ipnserver/server.go

@@ -1,6 +1,8 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
+// Package ipnserver runs the LocalAPI HTTP server that communicates
+// with the LocalBackend.
 package ipnserver
 
 import (

ipn/store/kubestore/store_kube.go

@@ -2,7 +2,6 @@
 // SPDX-License-Identifier: BSD-3-Clause
 
 // Package kubestore contains an ipn.StateStore implementation using Kubernetes Secrets.
-
 package kubestore
 
 import (

k8s-operator/apis/doc.go

@@ -3,6 +3,7 @@
 
 //go:build !plan9
 
+// Package apis contains a constant to name the Tailscale Kubernetes Operator's schema group.
 package apis
 
 const GroupName = "tailscale.com"

k8s-operator/utils.go

@@ -3,6 +3,7 @@
 
 //go:build !plan9
 
+// Package kube contains types and utilities for the Tailscale Kubernetes Operator.
 package kube
 
 import (

kube/fake_client.go

@@ -1,9 +1,6 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
-// Package kube provides a client to interact with Kubernetes.
-// This package is Tailscale-internal and not meant for external consumption.
-// Further, the API should not be considered stable.
 package kube
 
 import (

kube/grants.go

@@ -1,9 +1,6 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
-// Package kube provides a client to interact with Kubernetes.
-// This package is Tailscale-internal and not meant for external consumption.
-// Further, the API should not be considered stable.
 package kube
 
 import "net/netip"

logtail/example/logadopt/logadopt.go

@@ -1,6 +1,7 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
+// Command logadopt is a CLI tool to adopt a machine into a logtail collection.
 package main
 
 import (

net/dns/config.go

@@ -1,6 +1,7 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
+// Package dns contains code to configure and manage DNS settings.
 package dns
 
 import (

net/netmon/state.go

@@ -1,7 +1,6 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
-// Package interfaces contains helpers for looking up system network interfaces.
 package netmon
 
 import (

net/netstat/netstat_windows.go

@@ -1,7 +1,6 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
-// Package netstat returns the local machine's network connection table.
 package netstat
 
 import (

net/netutil/ip_forward.go

@@ -1,7 +1,6 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
-// Package netutil contains misc shared networking code & types.
 package netutil
 
 import (

net/tstun/wrap.go

@@ -1,8 +1,6 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
-// Package tstun provides a TUN struct implementing the tun.Device interface
-// with additional features as required by wgengine.
 package tstun
 
 import (

pkgdoc_test.go

@@ -0,0 +1,75 @@
+// Copyright (c) Tailscale Inc & AUTHORS
+// SPDX-License-Identifier: BSD-3-Clause
+
+package tailscaleroot
+
+import (
+	"go/parser"
+	"go/token"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+func TestPackageDocs(t *testing.T) {
+	switch runtime.GOOS {
+	case "darwin", "linux":
+		// Enough coverage for CI+devs.
+	default:
+		t.Skipf("skipping on %s", runtime.GOOS)
+	}
+
+	var goFiles []string
+	err := filepath.Walk(".", func(path string, fi os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if fi.Mode().IsRegular() && strings.HasSuffix(path, ".go") {
+			if strings.HasSuffix(path, "_test.go") {
+				return nil
+			}
+			goFiles = append(goFiles, path)
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	byDir := map[string][]string{} // dir => files
+	for _, fileName := range goFiles {
+		fset := token.NewFileSet()
+		f, err := parser.ParseFile(fset, fileName, nil, parser.PackageClauseOnly|parser.ParseComments)
+		if err != nil {
+			t.Fatalf("failed to ParseFile %q: %v", fileName, err)
+		}
+		dir := filepath.Dir(fileName)
+		if _, ok := byDir[dir]; !ok {
+			byDir[dir] = nil
+		}
+		if f.Doc != nil {
+			byDir[dir] = append(byDir[dir], fileName)
+			txt := f.Doc.Text()
+			if strings.Contains(txt, "SPDX-License-Identifier") {
+				t.Errorf("the copyright header for %s became its package doc due to missing blank line", fileName)
+			}
+		}
+	}
+	for dir, ff := range byDir {
+		switch dir {
+		case "tstest/integration/vms":
+			// This package has a couple go:build ignore commands and this test doesn't
+			// handle parsing those. Just allowlist that package for now (2024-07-10).
+			continue
+		}
+		if len(ff) > 1 {
+			t.Logf("multiple files with package doc in %s: %q", dir, ff)
+		}
+		if len(ff) == 0 {
+			t.Errorf("no package doc in %s", dir)
+		}
+	}
+	t.Logf("parsed %d files", len(goFiles))
+}

posture/doc.go

@@ -0,0 +1,6 @@
+// Copyright (c) Tailscale Inc & AUTHORS
+// SPDX-License-Identifier: BSD-3-Clause
+
+// Package posture contains functions to query the local system
+// state for managed posture checks.
+package posture

tailcfg/tailcfg.go

@@ -1,6 +1,8 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
+// Package tailcfg contains types used by the Tailscale protocol with between
+// the node and the coordination server.
 package tailcfg
 
 //go:generate go run tailscale.com/cmd/viewer --type=User,Node,Hostinfo,NetInfo,Login,DNSConfig,RegisterResponse,RegisterResponseAuth,RegisterRequest,DERPHomeParams,DERPRegion,DERPMap,DERPNode,SSHRule,SSHAction,SSHPrincipal,ControlDialPlan,Location,UserProfile --clonefunc

tool/gocross/gocross.go

@@ -8,7 +8,6 @@
 // In short, when aliased to `go`, using `go build`, `go test` behave like the
 // upstream Go tools, but produce correctly configured, correctly linked
 // binaries stamped with version information.
-
 package main
 
 import (

tstest/integration/vms/gen/test_codegen.go

@@ -1,51 +0,0 @@
-// Copyright (c) Tailscale Inc & AUTHORS
-// SPDX-License-Identifier: BSD-3-Clause
-
-// build ignore
-
-package main
-
-import (
-	_ "embed"
-	"log"
-	"os"
-
-	"github.com/dave/jennifer/jen"
-	"github.com/iancoleman/strcase"
-	"tailscale.com/tstest/integration/vms"
-)
-
-func main() {
-	f := jen.NewFile("vms")
-	f.Comment("Code generated by tstest/integration/vms/gen/test_codegen.go DO NOT EDIT.")
-
-	ptr := jen.Op("*")
-
-	for i, d := range vms.Distros {
-		f.Func().
-			Id("TestRun" + strcase.ToCamel(d.Name)).
-			Params(jen.Id("t").Add(ptr).Qual("testing", "T")).
-			BlockFunc(func(g *jen.Group) {
-				g.Id("t").Dot("Parallel").Call()
-				g.Id("setupTests").Call(jen.Id("t"))
-				g.Id("testOneDistribution").Call(jen.Id("t"), jen.Lit(i), jen.Id("Distros").Index(jen.Lit(i)))
-			})
-	}
-
-	os.Remove("top_level_test.go")
-	fout, err := os.Create("top_level_test.go")
-	if err != nil {
-		log.Fatal(err)
-	}
-	defer fout.Close()
-
-	fout.WriteString("// Copyright (c) Tailscale Inc & AUTHORS\n")
-	fout.WriteString("// SPDX-License-Identifier: BSD-3-Clause\n")
-	fout.WriteString("\n")
-	fout.WriteString("// +build linux\n\n")
-
-	err = f.Render(fout)
-	if err != nil {
-		log.Fatal(err)
-	}
-}

tstest/tools/tools.go

@@ -1,11 +1,10 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
-// This file exists just so `go mod tidy` won't remove
-// tool modules from our go.mod.
-
 //go:build tools
 
+// This file exists just so `go mod tidy` won't remove
+// tool modules from our go.mod.
 package tools
 
 import (

types/key/doc.go

@@ -0,0 +1,6 @@
+// Copyright (c) Tailscale Inc & AUTHORS
+// SPDX-License-Identifier: BSD-3-Clause
+
+// Package key contains types for different types of public and private keys
+// used by Tailscale.
+package key

util/limiter/limiter.go

@@ -1,6 +1,7 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
+// Package limiter provides a keyed token bucket rate limiter.
 package limiter
 
 import (

util/linuxfw/linuxfw.go

@@ -1,10 +1,9 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
-// Package linuxfw returns the kind of firewall being used by the kernel.
-
 //go:build linux
 
+// Package linuxfw returns the kind of firewall being used by the kernel.
 package linuxfw
 
 import (

util/osdiag/internal/wsc/wsc_windows.go

@@ -3,6 +3,7 @@
 
 // Code generated by 'go generate'; DO NOT EDIT.
 
+// Package wsc provides access to the Windows Security Center API.
 package wsc
 
 import (

util/osshare/filesharingstatus_windows.go

@@ -1,8 +1,8 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
-//go:build windows
-
+// Package osshare provides utilities for enabling/disabling Taildrop file
+// sharing on Windows.
 package osshare
 
 import (

util/winutil/authenticode/authenticode_windows.go

@@ -1,6 +1,7 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
+// Package authenticode contains Windows Authenticode signature verification code.
 package authenticode
 
 import (

util/winutil/testdata/testrestartableprocesses/restartableprocess_windows.go

@@ -1,6 +1,7 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
+// The testrestartableprocesses is a program for a test.
 package main
 
 import (

util/winutil/winenv/mksyscall.go

@@ -1,5 +1,6 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
+
 package winenv
 
 //go:generate go run golang.org/x/sys/windows/mkwinsyscall -output zsyscall_windows.go mksyscall.go

wf/firewall.go

@@ -3,6 +3,7 @@
 
 //go:build windows
 
+// Package wf controls the Windows Filtering Platform to change Windows firewall rules.
 package wf
 
 import (

wgengine/wgengine.go

@@ -1,6 +1,7 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
+// Package wgengine provides the Tailscale WireGuard engine interface.
 package wgengine
 
 import (

wgengine/winnet/winnet.go

@@ -3,6 +3,7 @@
 
 //go:build windows
 
+// Package winnet contains Windows-specific networking code.
 package winnet
 
 import (