Jsdoc
Use when writing or reviewing JSDoc on JavaScript/TypeScript functions, for required tags, typedef rules, and formatting. Opinionated JS/TS documentation standard.From its SKILL.md
npx -y skills add ioncache/ioncache-ai-tools --skill jsdocAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
3.5 KB, as published. Nobody here has run it
JSDoc Documentation Standards
CRITICAL REQUIREMENTS
- Every function MUST have JSDoc, no exceptions
- NO inline type definitions, use typedefs or imported types
- Import types from packages, use
import('package').Typesyntax - Include function description, clear explanation of what it does
- Add @example for functions with I/O, show actual usage patterns
- Add @throws for each error type, document every throw statement with specific error condition
Type Definition Rules
Use import() for external types:
/**
* @typedef {import('fastify').FastifyInstance} FastifyInstance
* @typedef {import('mongodb').Collection} Collection
*/
Define custom types as typedefs:
/**
* @typedef {'optimal'|'warning'|'danger'} RangeType
* @typedef {Object} EncounterFilters
* @property {string} [member_id] - Member UUID
* @property {string} [staff_id] - Staff UUID
* @property {number} [page=1] - Page number
* @property {number} [limit=100] - Items per page
*/
Use [...] for arrays, not Array<...>:
@param {[number, number][]} ranges - Array of [min, max] pairs
@returns {string[]} Array of user IDs
Complete Function Documentation
Every function needs:
- Description, what the function does
- @param, all parameters with imported/typedef types
- @returns, return type (use
Promise<Type>for async) - @throws, document error conditions
- @example, usage example for functions with parameters or return values
/**
* Retrieves and enriches records with optional pagination.
*
* @param {import('mongodb').Collection} collection - MongoDB collection
* @param {EncounterFilters} filters - Filter criteria
* @returns {Promise<object>} Enriched results
* @throws {Error} When the database operation fails
*
* @example
* const result = await getRecords(collection, {
* member_id: 'uuid-123',
* page: 1,
* limit: 50
* })
*/
async function getRecords(collection, filters) {
// Implementation
}
Type Accuracy Checklist
When documenting types, verify:
- Types match actual data passed to function
- Return types match actual returned data
- Optional params marked with
[param]or[param=default] - Nullable types marked with
|nullor|undefined - Union types used for multiple accepted types
- No inline
Object, use typedef or imported type - Array element types specified:
[ElementType] - Async functions return
Promise<Type>
Common Patterns
Optional parameters with defaults:
@param {number} [page=1] - Page number
@param {boolean} [include_counts=false] - Include counts
Multiple type options:
@param {string|number} id - User ID
@returns {User|null} User object or null if not found
Destructured parameters:
Define a typedef for the parameter object and reference it. Never use an inline
{Object} (see CRITICAL REQUIREMENTS).
/**
* @typedef {Object} ProcessOptions
* @property {string} memberId - Member UUID
* @property {boolean} [includeCounts] - Include counts
*/
/**
* @param {ProcessOptions} options
*/
function process({ memberId, includeCounts }) {}
Callback/function types:
@param {(error: Error|null, result: any) => void} callback