Public types exported and JSDoc-commented

Exported functions and types without JSDoc force every consumer to read the implementation to understand what the module expects, what it returns, and when it throws. ISO 25010:2011 §6.5.2 classifies undocumented public API surfaces as a maintainability defect. In practice, this means every integration with an undocumented utility function is a guess — and wrong guesses about parameter contracts (e.g., whether an ID parameter is the database row ID or the external API ID) produce bugs that only surface in production data.

Add JSDoc to every exported function and public type at module boundaries. Prioritize src/lib/, src/api/, and src/services/ — these are the highest-consumption surfaces.

/**
 * Represents a paginated API response.
 * @template T - The type of items in the results array.
 */
export interface PaginatedResponse<T> {
  /** Items for the current page. */
  items: T[]
  /** Total item count across all pages. */
  total: number
  /** Current page number, 1-indexed. */
  page: number
}

/**
 * Fetches a paginated list of users.
 * @param page - Page number to fetch (1-indexed).
 * @param pageSize - Items per page (default 20, max 100).
 * @returns Paginated user results, or throws UserFetchError on failure.
 */
export async function getUsers(page: number, pageSize = 20): Promise<PaginatedResponse<User>> {
  // ...
}

• ID: code-quality-essentials.organization.public-types-exported

• Severity: medium

• What to look for: Look for exported types and interfaces in the codebase — export type, export interface, export enum. For each public type, check whether it has a JSDoc comment (/** ... */) explaining its purpose, key fields, and usage context. Focus on types that form the public surface of modules: types exported from index.ts files, types used as function parameters or return values in exported functions, and types in lib/ or api/ directories. Internal implementation types don't need exhaustive documentation, but any type that a module consumer would need to work with should be documented. Also check whether key exported functions have JSDoc comments with @param and @returns annotations.

• Pass criteria: Enumerate all relevant code locations. Types on the public surface of key modules are exported and accompanied by JSDoc comments. Function signatures at module boundaries have @param and @returns JSDoc with at least 1 verified location.

• Fail criteria: Public types and exported functions have no documentation; consumers must read the implementation to understand how to use them.

• Skip (N/A) when: Purely internal application with no module boundaries that need documentation (small single-file-per-feature projects).

• Detail on fail: "Exported functions and types in src/lib/ lack JSDoc comments; callers must read implementation to understand usage"

• Remediation: Add JSDoc to public module surfaces:

  /**
   * Represents a paginated response from the API.
   * @template T - The type of items in the results array.
   */
  export interface PaginatedResponse<T> {
    /** The items for the current page. */
    items: T[]
    /** Total item count across all pages. */
    total: number
    /** Current page number, 1-indexed. */
    page: number
    /** Number of items per page. */
    pageSize: number
  }
  
  /**
   * Fetches a paginated list of users from the API.
   * @param page - Page number to fetch (1-indexed).
   * @param pageSize - Items per page (default 20, max 100).
   * @returns Paginated user results, or throws UserFetchError on failure.
   */
  export async function getUsers(page: number, pageSize = 20): Promise<PaginatedResponse<User>> {
    // ...
  }