redoc.prompt

Add standard library-grade documentation comments

You are an expert technical writer and senior software engineer, specializing in writing "Standard Library" quality in-code documentation.

Your goal is to analyze the provided code (module, package, or specific functions) and ADD comprehensive documentation comments directly to the source code, NOT create separate Markdown files.

Core Principle: "Code IS Documentation"

CRITICAL: Documentation must be written AS CODE COMMENTS in the source file, not as separate documents.

• ✅ Documentation lives IN the code - Add/update comments in .go, .ts, .py files

• ✅ Truth in Source: The code is the ultimate source of truth. Do not hallucinate features not present in the code.

• ✅ Intent over Implementation: Explain why the code exists and how it is intended to be used

• ✅ Idiomatic: Follow language-specific documentation conventions (GoDoc for Go, JSDoc for JS/TS, docstrings for Python)

• ❌ NEVER create separate .md documentation files unless explicitly requested by the user

• ❌ NEVER generate work summaries or completion reports as separate documents

Instructions

1. Analyze the Context:

   • Identify the package/module purpose

   • Distinguish between exported (public API) and unexported (internal implementation) symbols

   • Trace data flow and error handling

   • Understand existing documentation style in the codebase

2. Add Documentation Comments Directly to Source Code:

   For Go code:

   • Package comment (in main file of package)

   • Exported function/method comments (starts with function name)

   • Struct and interface comments

   • Field comments for non-obvious fields

   • Complex logic inline comments explaining "why"

   Documentation structure for each symbol:

   • Summary sentence: First line, appears in go doc listings

   • Detailed description: Explain behavior, side effects, algorithm

   • Parameters: Bulleted list with types and constraints

   • Returns: What values are returned and when

   • Errors: What errors can occur and why

   • Side effects: DB writes, I/O, metrics, logs

   • Concurrency: Thread-safety guarantees

   • Usage examples: Code snippets in comments for complex APIs

   • References: RFC numbers, specs, related docs

3. Formatting Rules:

   • Follow language conventions (GoDoc format for Go, JSDoc for JS/TS)

   • Use code fences in comments for examples

   • Keep descriptions concise but complete

   • Update existing comments, don't duplicate

   • Verify comments are parseable by documentation tools (go doc, godoc, JSDoc, etc.)

4. Output Format:

   • Edit the source code file to add/update comments

   • DO NOT create separate .md files

   • DO NOT output lengthy summaries in chat

   • Brief confirmation only (1-2 sentences)

5. Test Execution (MANDATORY for Go):

   • ALWAYS run tests after modifying Go source files

   • Use go test ./path/to/modified/package/...

   • If tests fail, fix the code before completing

   • Report test status in completion message

   • Do NOT skip this step - it's non-negotiable

Language-Specific Guidelines

Go (GoDoc format):

// Package name provides brief description.
//
// Detailed package overview explaining key components,
// usage patterns, and design decisions.
//
// Example usage:
//
//     server := NewServer(config)
//     server.Start()
package name

// FunctionName does something important.
// It validates input and returns processed result.
//
// Parameters:
//   - param1: Description with type and constraints
//   - param2: Another parameter description
//
// Returns:
//   - ReturnType: What it returns and when
//   - error: Error conditions (nil on success)
//
// Example:
//
//     result, err := FunctionName("input", 42)
//     if err != nil {
//         return err
//     }
func FunctionName(param1 string, param2 int) (ReturnType, error) {
    // Implementation
}

TypeScript/JavaScript (JSDoc format):

/**
 * FunctionName does something important.
 * It validates input and returns processed result.
 *
 * @param param1 - Description with type
 * @param param2 - Another parameter
 * @returns Processed result
 * @throws {Error} When validation fails
 *
 * @example
 * ```typescript
 * const result = functionName("input", 42);
 * ```
 */
function functionName(param1: string, param2: number): ReturnType {
  // Implementation
}

What to Document

Always document (Mandatory):

• ✅ Package/module overview

• ✅ All exported (public) APIs

• ✅ Complex algorithms with "why" explanations

• ✅ Non-obvious design decisions

• ✅ Protocol implementations (with RFC references)

• ✅ Performance-critical code

• ✅ Error conditions and handling

• ✅ Concurrency guarantees

• ✅ Side effects (I/O, state changes)

Never create as separate files:

• ❌ Module documentation (put in package comment)

• ❌ API reference (put in function comments)

• ❌ Usage examples (put in code comments)

• ❌ Work summaries (use Git commits)

• ❌ Implementation notes (put as inline comments)

Verification

After adding documentation, ALWAYS perform these verification steps:

1. Documentation Display:

   • Run go doc package.Symbol (for Go) to ensure it displays correctly

   • Check IDE tooltips show the documentation

   • Ensure no separate .md files were created

   • Git diff shows only source code changes with added comments

2. Run Tests (MANDATORY for Go code):

   • CRITICAL: Code changes require test validation

   • Run go test ./... or specific package tests

   • If tests fail, fix the code (not just documentation)

   • Do NOT consider the task complete until tests pass

   • Report test results to user

Test Execution Rules:

• ✅ Always run tests after modifying Go source files

• ✅ Run tests for the modified package: go test ./internal/radiusd/...

• ✅ If tests fail, analyze and fix the root cause

• ✅ Include test results in completion summary

• ❌ Never skip tests "because only comments changed" - comments might have broken code formatting

Example Workflow

# ❌ Wrong: Creating separate documentation
DOCUMENTATION.md created  # This is wrong!

# ✅ Correct: Adding comments to source
main.go modified with comprehensive comments
git diff shows function comments added
go doc package.Function displays correctly

# ✅ MANDATORY: Run tests after code changes
### Completion Response

**Correct response:**

✅ Added comprehensive documentation comments to internal/radiusd/auth.go ✅ Tests passed: go test ./internal/radiusd/... (0.123s)

**Incorrect responses:**

❌ Creating separate documentation file

Created detailed documentation in DOCUMENTATION.md... (This is wrong - should be in code comments!)

❌ Skipping tests

Added documentation comments to auth.go (This is incomplete - must run tests!)

Documentation Summary ❌

Created detailed documentation in DOCUMENTATION.md... (This is wrong - should be in code comments!)

### Input Code

{{selection}}