Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →aiskillstore/typescript-jsdoc
Write effective JSDoc comments for TypeScript code. Provides guidance on documentation format, strategic placement, best practices, and when to document versus when to keep code self-documenting. Helps maintain code clarity and IDE support.
Passed 22 of 22 test cases with the skill, and 19 of 22 without it.
3 fixed19 passed either way0 still failing0 broke
Tokens, turns and time describe resource use, not a dollar price.
One of 3 test cases the skill fixed. Same model, same prompt, with and without the skill.
I have a TypeScript function `function searchUsers(query: string): User[]` that currently uses an in-memory binary search tree, but we plan to switch to a trie index next sprint. What details should I emphasize in the JSDoc description?
| Checked | Without skill | With skill |
|---|---|---|
| The JSDoc description focuses on the function contract and promises. | Passed | Passed |
| The JSDoc omits internal implementation details like data structure choices. | Missed | Passed |
The instructions your model reads when the skill loads.
Write effective JSDoc comments that enhance code maintainability and provide valuable context to developers and IDEs.
JSDoc comments begin with /** and end with */, with lines inside typically starting with an asterisk. Tags start with @ followed by a keyword. Essential tags include @param, @returns, @throws, @example, and @deprecated.
Since TypeScript code already contains type information, JSDoc should focus on the "why" and "how" rather than repeating types:
/**
* Calculates the total price including tax
* @param basePrice - The price before tax
* @param taxRate - The tax rate as a decimal (0.08 for 8%)
* @returns The total price after applying tax
*/
function calculateTotal(basePrice: number, taxRate: number): number {
return basePrice * (1 + taxRate);
}
Treat JSDoc usage as having three distinct levels, each serving different purposes:
Essential Documentation appears on all public APIs, exported functions, classes, and interfaces. This is non-negotiable for library code or shared modules. Document what the entity does, important behaviors, potential errors, and provide a usage example when the interface isn't immediately obvious.
Clarifying Documentation becomes valuable when code has non-obvious behavior, implements complex algorithms, or has important side effects. Explain critical behaviors that aren't apparent from the signature, warn about unusual performance characteristics, or document retry logic, caching behavior, or state management. This documentation adds genuine value beyond the type system.
Minimal Documentation applies to internal helper functions, private methods, and straightforward utility functions where the code is genuinely self-documenting. Even here, a brief one-liner explaining intent helps future developers quickly understand purpose. Skip documentation only when the function name and implementation are immediately transparent.
For classes and services, document the class at a high level, then provide detailed documentation on public methods:
/**
* Manages user authentication and session handling.
*
test cases passed, vs 19 / 22 without
More skills from the same source and nearby in the registry, with their headline benchmark lift.