jsdoc-tsdoc
JSDoc and TSDoc documentation standards. Covers syntax, tags, TypeScript integration, documentation generation, and API documentation best practices. USE WHEN: user mentions "TSDoc", "TypeScript documentation", "API documentation", asks about "documenting TypeScript", "@param", "@returns", "TypeDoc", "API Extractor", "documentation tags" DO NOT USE FOR: JavaScript-only JSDoc - use `jsdoc` skill for plain JavaScript
How do I install this agent skill?
npx skills add https://github.com/claude-dev-suite/claude-dev-suite --skill jsdoc-tsdocIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides comprehensive instructions on JSDoc and TSDoc documentation standards, including syntax, tags, and integration with TypeScript. It recommends standard industry tools for documentation generation and linting, with no security risks detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
2 files scanned · No issues
What does this agent skill do?
JSDoc & TSDoc Documentation
Full Reference: See advanced.md for JSDoc type annotations in JavaScript, TypeDoc/API Extractor configuration, ESLint plugin setup, and README templates.
Deep Knowledge: Use
mcp__documentation__fetch_docswith technology:jsdocfor comprehensive tag reference.
When NOT to Use This Skill
- Plain JavaScript projects - Use the
jsdocskill for JavaScript-specific JSDoc patterns - Code comments (non-API) - TSDoc is for public API documentation, not inline code comments
- Auto-generated docs from code - Use TypeDoc or API Extractor tools directly
TSDoc vs JSDoc
| Feature | JSDoc | TSDoc |
|---|---|---|
| Purpose | JS documentation + types | TS documentation only |
| Type annotations | @type, @param {Type} | Not needed (use TS types) |
| Standardization | De facto | Formal standard |
Use TSDoc for TypeScript projects - types come from TypeScript, comments describe behavior.
Function Documentation
/**
* Calculates the total price including tax.
*
* @remarks
* This method uses the default tax rate unless overridden.
* For international orders, use {@link calculateInternationalPrice} instead.
*
* @param basePrice - The pre-tax price in cents
* @param taxRate - Tax rate as decimal (default: 0.1 for 10%)
* @returns The total price including tax in cents
*
* @throws {@link InvalidPriceError}
* Thrown if basePrice is negative
*
* @example
* ```typescript
* const total = calculateTotalPrice(1000, 0.08);
* console.log(total); // 1080
* ```
*
* @beta
*/
function calculateTotalPrice(basePrice: number, taxRate = 0.1): number {
if (basePrice < 0) {
throw new InvalidPriceError('Price cannot be negative');
}
return Math.round(basePrice * (1 + taxRate));
}
Interface Documentation
/**
* Configuration options for the HTTP client.
*
* @remarks
* All timeouts are in milliseconds.
*
* @public
*/
interface HttpClientOptions {
/**
* Base URL for all requests.
* @example 'https://api.example.com/v1'
*/
baseUrl: string;
/**
* Request timeout in milliseconds.
* @defaultValue 30000
*/
timeout?: number;
/**
* Maximum number of retry attempts for failed requests.
* @defaultValue 3
*/
maxRetries?: number;
}
All TSDoc Tags
Block Tags
| Tag | Usage |
|---|---|
@param name - description | Parameter documentation |
@returns description | Return value description |
@throws {Type} description | Thrown exceptions |
@example | Usage examples (code block) |
@remarks | Extended description |
@see | Related references |
@deprecated reason | Mark as deprecated |
@defaultValue value | Default value |
@typeParam T - description | Generic type parameter |
Modifier Tags
| Tag | Meaning |
|---|---|
@public | Part of public API |
@internal | Internal implementation |
@alpha | Early preview, may change |
@beta | Maturing, API may change |
@readonly | Read-only property |
@override | Overrides parent |
Inline Tags
| Tag | Usage |
|---|---|
{@link Target} | Link to symbol |
{@link Target | text} | Link with custom text |
{@inheritDoc Parent.method} | Inherit documentation |
Anti-Patterns
| Anti-Pattern | Why It's Wrong | Correct Approach |
|---|---|---|
| Documenting types in TypeScript | Redundant, types already in signature | Describe behavior, not types |
| Copy-pasting function signature | Adds no value, desynchronizes | Explain purpose, edge cases, examples |
Missing @example for complex APIs | Users don't know how to use it | Always include usage examples |
Using @deprecated without migration | Users don't know what to use instead | @deprecated Use {@link newFunction} instead |
No @throws documentation | Users don't know what to catch | Document all thrown exceptions |
Quick Troubleshooting
| Issue | Diagnosis | Solution |
|---|---|---|
| VS Code not showing docs on hover | Malformed JSDoc comment | Ensure /** start and proper tag syntax |
eslint-plugin-tsdoc errors | Invalid TSDoc syntax | Fix tag formatting per TSDoc spec |
| TypeDoc ignoring comments | Wrong comment location | Place JSDoc directly above declaration |
{@link} not resolving | Incorrect symbol reference | Use fully qualified name or import path |
Official References
| Resource | URL |
|---|---|
| TSDoc | https://tsdoc.org/ |
| JSDoc | https://jsdoc.app/ |
| TypeDoc | https://typedoc.org/ |
| API Extractor | https://api-extractor.com/ |
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/claude-dev-suite/claude-dev-suite/jsdoc-tsdoc">View jsdoc-tsdoc on skillZs</a>