Goal
Enable clear intent, safer refactors, and accurate AI assistance by documenting real function behavior using TSDoc validated through execution.
Rule Behavior
1️⃣ Document Intent to Guide Runtime Expectations
- Describe what the function achieves and why it exists
- Include expected side effects and responsibilities
2️⃣ Specify Input Meaning and Boundaries
- Define parameter purpose and constraints
- Mark nullable, optional, or restricted values
3️⃣ Define Output Shape and Error Behavior
- Provide return type expectations and failure conditions
- Help Agent validate runtime safety of edge cases
4️⃣ Keep Docs Synced With Execution Logs
- Update TSDoc when code behavior or shape changes
- Use runtime feedback to detect outdated documentation
5️⃣ Prioritize High Usage Modules First
- Document shared utilities and domain models early
- Enable AI refactors without introducing misunderstandings
Examples
- "Add TSDoc describing intent and return type for this pricing utility."
- "Document error cases for this async fetch function."
Tool Prompts
- "Generate TSDoc for all exported functions with intent summaries."
- "Check for mismatches between TSDoc types and runtime values."
- "Extract interface from executed output and update TSDoc accordingly."
Quick Implementation Wins
- Add TSDoc to modules involved in user facing flows
- Include error notes for async behaviors
- Use documentation to drive better test case generation