all: clean up some godoc comments

Josh Bleecher Snyder created 1 month ago

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.

Change summary

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(-)

Detailed changes

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()

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] {

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

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")
 }