An undocumented public API surface forces every consumer to read the source to understand what a function accepts, what it returns, and when it throws. At scale this is a critical iso-25010:2011 analysability failure: every hour a developer spends reading implementation code instead of documentation is a direct tax on adoption and integration speed. The 80% coverage threshold exists because partial documentation is worse than none — it creates false confidence, leaving the undocumented 20% as silent landmines. TypeScript types alone do not satisfy this: a type signature names parameters but doesn't explain their semantics, valid ranges, or side effects.
Critical because an undocumented API surface makes the project unusable to any developer without source access, and partial documentation creates false confidence that leads to incorrect integrations at runtime.
Document every exported function with a description, parameter descriptions, and return type. Type annotations are not sufficient — add prose explaining semantics:
/**
* Creates a configured client for the API.
*
* @param options.apiKey - Your API key (generate at https://example.com/keys)
* @param options.baseUrl - Override the default API host (default: https://api.example.com)
* @returns A client instance ready to make requests
*
* @example
* const client = createClient({ apiKey: process.env.API_KEY })
*/
export function createClient(options: ClientOptions): Client
Run coverage with typedoc or jsdoc and verify at least 80% of exported symbols have prose descriptions before shipping.
ID: developer-documentation.api-reference.public-api-docs
Severity: critical
What to look for: Identify the project's public API surface -- exported functions, classes, methods, CLI commands, REST endpoints, or React components. Then check whether each is documented with a description, parameter types, and return types. Documentation can be in a docs site, README, or generated (typedoc, jsdoc). The key question: can a developer use each exported function without reading the source code? Count every public API endpoint in the codebase (by scanning route files) and count every documented endpoint. Report the ratio: X of Y endpoints are documented.
Pass criteria: Every exported function, class, method, endpoint, or component is documented with: (1) a description of what it does, (2) all parameters with types and descriptions, (3) return type or response format. Documentation covers at least 80% of the public API surface. Report even on pass: "X of Y public endpoints documented (Z% coverage)."
Fail criteria: Major exported functions or endpoints have no documentation, or documentation exists but omits parameter descriptions or return types. Common pattern: typedoc/jsdoc is configured but most functions have no docstrings, so generated docs show only type signatures with no explanation. Do NOT pass if fewer than 80% of public API endpoints are documented — partial coverage creates a false sense of completeness.
Skip (N/A) when: The project has no public API -- it is a standalone application with no exported modules, CLI commands, or API endpoints that other developers would consume.
Cross-reference: The auth-docs check verifies that authentication — often the most complex API topic — is documented with the same completeness.
Detail on fail: Example: "Project exports 15 functions from index.ts but only 3 have any documentation -- 12 functions have no description, parameter docs, or return type docs" or "API has 8 REST endpoints but no API reference documentation exists"
Remediation: Document each exported function at minimum with a description and parameter descriptions. For TypeScript projects, type annotations help but are not sufficient -- add prose descriptions:
/**
* Creates a new client instance for interacting with the API.
*
* @param options - Configuration options for the client
* @param options.apiKey - Your API key (get one at https://example.com/keys)
* @param options.baseUrl - Custom API base URL (default: https://api.example.com)
* @returns A configured client instance
*
* @example
* const client = createClient({ apiKey: 'sk-...' })
*/
export function createClient(options: ClientOptions): Client {