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

* ```typescript

* const result = myFunction(input);

* ```

*/

Class

/**

* [Brief description]

*

* [Design patterns, responsibilities]

*

* @example

* ```typescript

* 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.