Public API is documented
Why it matters
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.
Severity rationale
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.
Remediation
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.
DetectionPro
The detection method for this pattern is part of AuditBuffet Pro.
The full method (what to look for, pass and fail conditions, and how results get reported) ships inside the Developer Documentation Audit. The pattern definition, severity rationale, and remediation remain openly licensed under CC-BY-4.0.
External references
- iso-25010:2011 · maintainability.analysability
Taxons
History
- 2026-04-18·v1.0.0·Initial import from developer-documentation·automated