Documentation patterns for software projects. Use when writing JSDoc, OpenAPI specs, ADRs, READMEs, CHANGELOGs, or API documentation.
Documentation patterns and standards for software projects. Covers JSDoc, OpenAPI/Swagger, Architecture Decision Records (ADR), README structure, CHANGELOG format, inline code comments, and API documentation best practices.
Use this skill when the user asks about:
/**
* Calculates the total price including tax and optional discount.
*
* @param items - Array of line items to calculate
* @param taxRate - Tax rate as a decimal (e.g., 0.08 for 8%)
* @param options - Optional calculation parameters
* @returns The calculated total with breakdown
*
* @example
* ```ts
* const total = calculateTotal(
* [{ name: "Widget", price: 9.99, quantity: 2 }],
* 0.08,
* { discount: 0.1 }
* );
* // { subtotal: 19.98, tax: 1.60, discount: 2.00, total: 19.58 }
* ```
*
* @throws {ValidationError} If items array is empty
* @throws {RangeError} If taxRate is negative
*
* @see {@link LineItem} for item structure
* @since 2.1.0
*/
function calculateTotal(
items: LineItem[],
taxRate: number,
options?: CalculateOptions
): TotalBreakdown {
// ...
}
/**
* Configuration for the database connection pool.
*
* @remarks
* The pool automatically manages connections, creating new ones as needed
* up to {@link PoolConfig.max | max} and reaping idle connections after
* {@link PoolConfig.idleTimeoutMs | idleTimeoutMs}.
*/
interface PoolConfig {
/** PostgreSQL connection string */
connectionString: string;
/** Minimum number of connections to maintain. @defaultValue 2 */
min?: number;
/** Maximum number of connections allowed. @defaultValue 10 */
max?: number;
/**
* Time in milliseconds before an idle connection is closed.
* Set to 0 to disable.
* @defaultValue 30000
*/
idleTimeoutMs?: number;
/**
* Called when a connection is established.
* Use for per-connection setup (e.g., setting search_path).
*/
onConnect?: (client: PoolClient) => Promise<void>;
}
/**
* @module auth/jwt
* @description JWT token generation and verification utilities.
*
* Provides functions for creating access/refresh token pairs,
* verifying tokens, and extracting claims.
*
* @example
* ```ts
* import { signToken, verifyToken } from "@/auth/jwt";
*
* const token = await signToken({ userId: "123", role: "admin" });
* const claims = await verifyToken(token);
* ```
*
* @packageDocumentation
*/
/**
* HTTP status codes used across the API.
*
* @remarks
* Only includes status codes actively used by our endpoints.
* For the full HTTP spec, see {@link https://httpstatuses.com/}.
*/
enum HttpStatus {
/** Request succeeded */
OK = 200,
/** Resource created successfully */
Created = 201,
/** Request accepted for background processing */
Accepted = 202,
/** No content to return */
NoContent = 204,
/** Invalid request body or parameters */
BadRequest = 400,
/** Authentication required */
Unauthorized = 401,
/** Authenticated but insufficient permissions */
Forbidden = 403,
/** Resource not found */
NotFound = 404,
/** Server error */
InternalServerError = 500,
}