From 1a21f5eba67bf022734ae564d11ef6178541b65d Mon Sep 17 00:00:00 2001
From: Josh Bleecher Snyder <josharian@gmail.com>
Date: Thu, 5 Feb 2026 13:04:26 -0800
Subject: [PATCH] all: clean up some godoc comments

I noticed that one of the most common edits I made to Claude-written
code is improving godoc style.

Perhaps I should just let it go, but I can't.
Apparently I care more about writing than about code.

I wrote a little style guide for Claude and asked it to apply it
in a dozen places so I could spot-check it.
This was the result. I figured I may as well commit it.
---
 claudetool/bashkit/bashkit.go   | 3 +--
 claudetool/patchkit/patchkit.go | 8 ++++----
 gitstate/gitstate.go            | 2 +-
 server/handlers.go              | 2 +-
 4 files changed, 7 insertions(+), 8 deletions(-)

diff --git a/claudetool/bashkit/bashkit.go b/claudetool/bashkit/bashkit.go
index 4abf724a4df0615f9fd5af3bf25773c34bb71e25..048d847bdd3edd26973509496a63230f06e5cf4a 100644
--- a/claudetool/bashkit/bashkit.go
+++ b/claudetool/bashkit/bashkit.go
@@ -76,8 +76,7 @@ func Check(bashScript string) error {
 	return err
 }
 
-// WillRunGitCommit checks if the provided bash script will run 'git commit'.
-// It returns true if any command in the script is a git commit command.
+// WillRunGitCommit reports whether bashScript contains a git commit command.
 func WillRunGitCommit(bashScript string) (bool, error) {
 	r := strings.NewReader(bashScript)
 	parser := syntax.NewParser()
diff --git a/claudetool/patchkit/patchkit.go b/claudetool/patchkit/patchkit.go
index fe789f12cb014a83b366e5594386d80cf446444a..0d28984178255ae6cf2f302e38f7c481ccbc4a1e 100644
--- a/claudetool/patchkit/patchkit.go
+++ b/claudetool/patchkit/patchkit.go
@@ -390,9 +390,9 @@ func commonWhitespacePrefix(x []string) string {
 	return pre
 }
 
-// commonPrefixLen returns the length of the common prefix of two strings.
-// TODO: optimize, see e.g. https://go-review.googlesource.com/c/go/+/408116
+// commonPrefixLen returns the length of the common prefix of a and b.
 func commonPrefixLen(a, b string) int {
+	// TODO: optimize, see https://go-review.googlesource.com/c/go/+/408116
 	shortest := min(len(a), len(b))
 	for i := range shortest {
 		if a[i] != b[i] {
@@ -402,9 +402,9 @@ func commonPrefixLen(a, b string) int {
 	return shortest
 }
 
-// commonSuffixLen returns the length of the common suffix of two strings.
-// TODO: optimize
+// commonSuffixLen returns the length of the common suffix of a and b.
 func commonSuffixLen(a, b string) int {
+	// TODO: optimize
 	shortest := min(len(a), len(b))
 	for i := 0; i < shortest; i++ {
 		if a[len(a)-i-1] != b[len(b)-i-1] {
diff --git a/gitstate/gitstate.go b/gitstate/gitstate.go
index e9fac54fd3a198c6055be8692d144bd603499161..9da45d425dde9d556e773c4cb75ab1ffddcd5436 100644
--- a/gitstate/gitstate.go
+++ b/gitstate/gitstate.go
@@ -80,7 +80,7 @@ func GetGitState(dir string) *GitState {
 	return state
 }
 
-// Equal returns true if two git states are equal.
+// Equal reports whether g and other represent the same git state.
 func (g *GitState) Equal(other *GitState) bool {
 	if g == nil && other == nil {
 		return true
diff --git a/server/handlers.go b/server/handlers.go
index 6b71f60f9fe91fd91d6094eeddd247386ff61153..42304baa41bd044918636f01fa9d75baa0fec151 100644
--- a/server/handlers.go
+++ b/server/handlers.go
@@ -189,7 +189,7 @@ func isConversationSlugPath(path string) bool {
 	return strings.HasPrefix(path, "/c/")
 }
 
-// acceptsGzip returns true if the client accepts gzip encoding
+// acceptsGzip reports whether r accepts gzip encoding.
 func acceptsGzip(r *http.Request) bool {
 	return strings.Contains(r.Header.Get("Accept-Encoding"), "gzip")
 }