From ed377c93c6ec418ca3008451eeac252ce60e7602 Mon Sep 17 00:00:00 2001
From: AJ ONeal <aj@therootcompany.com>
Date: Sun, 8 Mar 2026 21:39:47 -0600
Subject: [PATCH] docs: rewrite package comments to focus on what/why, not how

Each package doc now explains what problem it solves and why it exists,
with the public interface as the only "how" detail. Implementation
notes removed from doc comments.
---
 internal/buildmeta/buildmeta.go   |  8 ++++++--
 internal/httpclient/httpclient.go | 19 ++++++++-----------
 internal/lexver/lexver.go         | 26 +++++++-------------------
 internal/uadetect/uadetect.go     | 15 ++++++---------
 4 files changed, 27 insertions(+), 41 deletions(-)

diff --git a/internal/buildmeta/buildmeta.go b/internal/buildmeta/buildmeta.go
index 51c9eef..d100bb7 100644
--- a/internal/buildmeta/buildmeta.go
+++ b/internal/buildmeta/buildmeta.go
@@ -1,5 +1,9 @@
-// Package buildmeta defines the canonical constants for OS, architecture,
-// libc, archive format, and release channel used throughout Webi.
+// Package buildmeta is the shared vocabulary for Webi's build targets.
+//
+// Every package that deals with OS, architecture, libc, archive format, or
+// release channel imports these types instead of passing raw strings. This
+// prevents typos like "darwn" from compiling and gives a single place to
+// enumerate what Webi supports.
 package buildmeta
 
 // OS represents a target operating system.
diff --git a/internal/httpclient/httpclient.go b/internal/httpclient/httpclient.go
index b14f5e2..32dcc9a 100644
--- a/internal/httpclient/httpclient.go
+++ b/internal/httpclient/httpclient.go
@@ -1,15 +1,12 @@
-// Package httpclient provides a resilient HTTP client with best-practice
-// defaults for making upstream API calls (GitHub, Gitea, etc.).
+// Package httpclient provides a secure, resilient HTTP client for upstream API
+// calls. It exists because [http.DefaultClient] has no timeouts, no retry
+// logic, and follows redirects from HTTPS to HTTP — none of which are
+// acceptable for a server making calls to GitHub, Gitea, etc. on behalf of
+// users.
 //
-// Features:
-//   - Sensible timeouts at every level (connect, TLS, headers, overall)
-//   - Connection pooling with reasonable limits
-//   - TLS 1.2+ minimum
-//   - Limited redirect depth, no HTTPS→HTTP downgrade
-//   - Automatic retries with exponential backoff + jitter for transient errors
-//   - Respects Retry-After headers
-//   - Custom User-Agent identifying Webi
-//   - All calls require context.Context
+// Create a [Client] with [New], then use [Client.Do] or [Client.Get]. All
+// calls require [context.Context] and will automatically retry transient
+// failures (429, 502, 503, 504) with backoff.
 package httpclient
 
 import (
diff --git a/internal/lexver/lexver.go b/internal/lexver/lexver.go
index 2595ae4..995e025 100644
--- a/internal/lexver/lexver.go
+++ b/internal/lexver/lexver.go
@@ -1,24 +1,12 @@
-// Package lexver converts version strings into lexicographically sortable
-// representations so that version comparison reduces to string comparison.
+// Package lexver makes version strings comparable via simple string comparison.
 //
-// The core problem: "1.20.3" must sort after "1.2.0", but as raw strings
-// "1.2" > "1.20" because '2' > '.' in ASCII. Lexver solves this by
-// zero-padding each numeric segment to a fixed width.
+// Version strings like "1.20.3" and "1.2.0" can't be compared as raw strings
+// because "1.2" > "1.20" in ASCII. Lexver normalizes them so that standard
+// string ordering matches semantic version ordering — including pre-release
+// channels (alpha < beta < rc < stable).
 //
-// Sorting rules:
-//   - Numeric segments are zero-padded and compared naturally
-//   - Stable releases sort after pre-releases of the same version
-//   - Pre-release channels sort alphabetically (alpha < beta < rc)
-//   - Numeric suffixes within channels sort numerically (rc2 > rc1)
-//
-// Examples:
-//
-//	"1.20.3"       → "0001.0020.0003.0000~"
-//	"1.0.0-beta1"  → "0001.0000.0000.0000-beta.0001"
-//	"1.0.0"        → "0001.0000.0000.0000~"
-//
-// The "~" character sorts after "-" in ASCII, so stable versions always
-// sort after any pre-release of the same numeric version.
+//	lexver.Parse("1.20.3") > lexver.Parse("1.2.0")    // true
+//	lexver.Parse("1.0.0")  > lexver.Parse("1.0.0-rc1") // true
 package lexver
 
 import (
diff --git a/internal/uadetect/uadetect.go b/internal/uadetect/uadetect.go
index f2157db..c049123 100644
--- a/internal/uadetect/uadetect.go
+++ b/internal/uadetect/uadetect.go
@@ -1,13 +1,10 @@
-// Package uadetect identifies OS, architecture, and libc from a User-Agent
-// string. The input is typically from curl's -A flag:
+// Package uadetect identifies the requesting system's OS, CPU architecture,
+// and libc from its User-Agent string.
 //
-//	curl -fsSA "$(uname -srm)" https://webi.sh/node
-//
-// Which produces something like:
-//
-//	"Darwin 23.1.0 arm64"
-//	"Linux 6.1.0 x86_64"
-//	"CYGWIN_NT-10.0-19045 3.5.3 x86_64"
+// Webi's bootstrap scripts send "$(uname -srm)" as the User-Agent, e.g.
+// "Darwin 23.1.0 arm64" or "Linux 6.1.0 x86_64". This package parses those
+// into [buildmeta.OS], [buildmeta.Arch], and [buildmeta.Libc] values so the
+// server can select the correct release artifact.
 package uadetect
 
 import (