# redoc.prompt

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):**

```go
// 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):**

````typescript
/**
 * 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

```bash
# ❌ 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}}
```