---
description: "Documentation standards and requirements"
globs:
alwaysApply: true
---

# Documentation Standards

## JSDoc Requirements

**All exported functions must have JSDoc** with:
- `@param` for each parameter
- `@returns` for return value
- `@throws` for errors thrown (if applicable)
```typescript
// ✅ GOOD
/**
 * Validates GitHub issue against spec requirements.
 * @param issue - GitHub issue data from API
 * @param spec - Spec to validate against
 * @returns true if issue satisfies spec requirements
 * @throws {ValidationError} if issue structure is invalid
 */
export function validateIssue(issue: GHIssue, spec: Spec): boolean {
  // Implementation
}

// ❌ BAD - no JSDoc
export function validateIssue(issue: GHIssue, spec: Spec): boolean {
  // Implementation
}
```

## Code Comments

- **Explain WHY, not WHAT** — code should be self-documenting
- **Keep comments current** — update when code changes
- **Avoid obvious comments** — `// increment counter` is noise
```typescript
// ✅ GOOD - explains reasoning
// Use Set for O(1) lookup when filtering duplicates
const uniqueIds = new Set(ids);

// ❌ BAD - states the obvious
// Create a new Set
const uniqueIds = new Set(ids);
```

## File Documentation

**Never auto-generate documentation files** unless explicitly requested.

See `99-no-unsolicited-docs.mdc` for policy.

## Memory Bank Updates

Document architectural decisions and patterns in Memory Bank:
- Major decisions → `memory-bank/systemPatterns.md`
- Current work → `memory-bank/activeContext.md`
- Learnings → `memory-bank/systemPatterns.md` (Patterns section)

---

## Summary

- JSDoc on all exported functions
- Comments explain WHY, not WHAT
- No auto-generated doc files
- Update Memory Bank for architectural changes

---

## Related Resources

- **No Auto-Generated Docs:** `99-no-unsolicited-docs.mdc` — Policy enforcement
- **Architectural Decisions:** `memory-bank/systemPatterns.md` — Pattern documentation
- **Code Examples:** See `04-coding-standards.mdc` for JSDoc patterns