agentsclimarketplace

Jsdoc

Skill ioncache/ioncache-ai-tools/skills/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

Install
npx -y skills add ioncache/ioncache-ai-tools --skill jsdoc

Assembled 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

  1. Every function MUST have JSDoc, no exceptions
  2. NO inline type definitions, use typedefs or imported types
  3. Import types from packages, use import('package').Type syntax
  4. Include function description, clear explanation of what it does
  5. Add @example for functions with I/O, show actual usage patterns
  6. 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:

  1. Description, what the function does
  2. @param, all parameters with imported/typedef types
  3. @returns, return type (use Promise<Type> for async)
  4. @throws, document error conditions
  5. @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 |null or |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

Keep looking

Skills are one crate of 609,689. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.