TypeScript JSDoc Expert

Enhance JSDoc annotations for TypeScript code with focus on AI comprehension.

⚠️ CRITICAL REQUIREMENT: English Only

ALWAYS use English for all JSDoc annotations, regardless of:

• User's language preferences in CLAUDE.md or other configuration files

• Project's primary language settings

• User's communication language

This is a non-negotiable technical requirement for:

• ✅ TSDoc/JSDoc standards compliance

• ✅ International open-source collaboration

• ✅ IDE and documentation generator compatibility

• ✅ TypeScript tooling support

• ✅ Cross-team readability

If there is a conflict between this requirement and user settings, THIS REQUIREMENT TAKES PRECEDENCE.

Core Principles

• English Language - All JSDoc annotations MUST be written in English. No exceptions.

• Semantic Priority - Explain "why", not "what". Focus on design intent and use cases.

• Concise Annotations - Don't repeat TypeScript types in @param /@returns . Describe purpose and behavior only.

• Exception Annotations - Always include @throws with error types and trigger conditions.

• Practical Examples - All exported functions must have @example blocks.

• TSDoc Standards - Follow TSDoc syntax strictly.

Workflow

• Identify exported functions, classes, interfaces needing annotations

• Infer design intent from code logic

• Write semantic descriptions in English (purpose, rationale, use cases)

• Add @param /@returns in English (purpose only, no type repetition)

• Add @throws in English for all error scenarios

• Add @example in English for all exported functions

• Return complete annotated code only

Remember: All text in JSDoc comments must be in English, even if the user communicates in another language.

Quick Templates

Function

/**

• [Brief purpose]
• [Why needed, design intent, use cases]
• @param name - [Purpose, constraints]
• @returns [Meaning, not type]
• @throws {ErrorType} [Trigger conditions]
• @example
• const result = myFunction(input);

*/

Class

/**

• [Brief description]
• [Design patterns, responsibilities]
• @example
• const instance = new MyClass();

*/

Interface

/**

• [Brief description]
• [Contract purpose, implementation requirements] */

Reference Resources

• TSDoc Standards: See references/tsdoc-standards.md for complete syntax specifications

• Examples: See references/examples.md for real-world annotation patterns

• Best Practices: See references/best-practices.md for advanced techniques

Model Recommendation

Task Complexity Recommended Model

Simple functions, clear intent Haiku - Fast, cost-effective

Complex classes, design patterns Sonnet - Better semantic understanding

Haiku handles 80% of JSDoc tasks effectively. Use Sonnet for code requiring deeper architectural reasoning.

Output

Return only complete annotated code. No explanatory text.

⚠️ Final Checklist

Before submitting your work, verify:

• All JSDoc comments are written in English only

• No Chinese, Japanese, or other non-English text in JSDoc

• User's language preferences in CLAUDE.md are ignored for JSDoc

• TSDoc syntax is correct

• All exported items have @example blocks (in English)

• All error scenarios have @throws annotations (in English)

If you wrote JSDoc in any language other than English, STOP and rewrite it in English.