review-godocs

name	review-godocs
description	Review Go packages for missing or non-idiomatic godoc comments and produce a concise coverage report and findings without modifying files. Use when auditing Go documentation quality.
license	Apache-2.0
compatibility	Requires Go toolchain (go) and git.
metadata	{"source":".prompts/review-godocs.md","version":"1.0"}

Prompt: Review Godoc Comments

Goal

Review existing Go documentation and identify missing or non-idiomatic godoc comments so every package, type, field, function, and method is documented in an idiomatic, stdlib-style way.

• Top-level package docs must use block comments /* ... */ in a dedicated doc.go.
• All other docs must use line comments // ... immediately preceding the declaration.
• Document everything (exported and unexported) — types, interfaces, funcs, methods, consts, vars, and every struct field.
  • Exception: embedded struct fields may omit comments if they’re purely structural.
• Follow Effective Go and Go Code Review Comments conventions.

Note: Tests are out of scope — see "Scope & Exclusions" below.

---

Tasks

• Inspect all packages and declarations.
• Produce a concise coverage report (documented vs total) per package and overall.
• List missing or non-idiomatic docs with quick-fix suggestions.
• Do not modify files; propose a patch in a separate section.

---

Scope & Exclusions

• Exclude test files: ignore any file matching *_test.go when reviewing coverage and style.
• Exclude test-only symbols: do not report or suggest docs for Test*, Benchmark*, or Fuzz* functions, even if they appear in non-test files.
• Build tags: if a file is guarded by a test-only build tag (e.g., //go:build test), treat it as excluded.
• You may read tests to infer intended public API behavior, but do not include test code in coverage metrics or findings.

---

Tooling (you may run)

# Enumerate packages (excluding vendor automatically)
go list ./...

# Show package import path & directory (if needed)
go list -json ./...

# Quick doc check (human read)
go doc -all <pkg>

# Git helpers for patching
git status
git diff

---

Style Rules (stdlib-like)

• First sentence: one-line summary, ends with a period, present tense, starts with the identifier’s name for exported symbols (preferably for unexported, too).

  • // Reader reads bytes from an underlying buffer.

• Package comment (in doc.go):

  • File header uses block form:

    /*
    Package foo provides ...
    
    Overview:
      - Short bullets are fine.
      - Keep lines ~80-100 cols.
    */
    package foo
    

• Types & Interfaces:

  • Explain what it represents and any invariants / zero-value behavior.

• Struct fields:

  • Precede each field with a one-line // comment.
  • Clarify units, accepted ranges, zero-value meaning, and concurrency expectations.

• Functions & Methods:

  • Describe behavior, notable side effects, error semantics, and constraints.
  • Note thread-safety and performance considerations where relevant.

• Constants & Vars:

  • Grouped blocks can share a short lead-in, but exported names should still be clear in context.

• Tags & Special Conventions:

  • Use Deprecated: prefix when applicable.
  • Avoid Markdown-heavy formatting; inline code with backticks is OK.
  • Keep it concise; prefer short paragraphs and bullets.

---

What to Extract While Learning

• Purpose of each package (what it does; who uses it).
• Zero values and invariants of primary types.
• Error model (sentinel errors, wrapping, context).
• Concurrency (goroutine safety, locking, channels).
• Performance and critical-path notes if visible from code/tests.
• Configuration and environment interactions.

---

Output: Review Report (for "review godocs")

1. Coverage Table (per package)

   • pkg path | total decls | documented | coverage %

2. Findings

   • Missing package comment (file/path)
   • Missing/short/anti-idiomatic docs with a one-line fix suggestion

3. Suggested Patch (preview)

   • Minimal diffs for the most important fixes

---

Minimal Algorithm

1. Enumerate packages with go list ./....

2. For each package:

   • Ignore files matching *_test.go and files gated by test-only build tags.
   • Check whether doc.go exists with a block comment; if missing, flag it.
   • Parse files and locate all declarations (types, interfaces, funcs/methods, consts, vars).
   • For structs, ensure each field has a // comment (skip pure embedded fields if intentional).
   • Skip functions named Test*, Benchmark*, or Fuzz* from review and metrics.
   • Check whether comments meet the Style Rules.

---

Quality Gates

• 100% documentation coverage for packages and top-level exported API (excluding tests).
• Unexported declarations documented unless intentionally private noise—prefer brief one-liners.
• First sentence present tense, ends with a period.
• No trailing whitespace; gofmt clean.