JSDoc for Public API Surfaces Only
You'll learn how to strategically document only your library's public exports with JSDoc, leaving internal implementation details untyped for faster iteration.
The Strategic Documentation Approach
When maintaining a JavaScript library or module, you don't need to annotate every single line of code. Instead, focus your JSDoc effort on the public API surface—the functions, classes, and types that external consumers interact with.
Think of your module like a building: visitors only need clear signage for entrances and public rooms, not for every electrical wire behind the walls. Internal helper functions and private utilities can remain untyped, allowing you to refactor rapidly without updating type annotations constantly.
Why This Works
Your exported functions are contracts with the outside world. They deserve precise documentation because:
- Breaking changes here affect users
- Type clarity helps consumers use your library correctly
- Editor autocompletion depends on these annotations
Your internal code is implementation detail. You can rewrite it freely without external consequences, so heavy type annotations just slow you down.
The Pattern
Document what crosses the boundary:
// Exported - fully documented
/**
* @param {string} userId
* @param {{name: string, email: string}} data
* @returns {Promise<User>}
*/
export function updateUser(userId, data) {
return processUpdate(userId, normalize(data));
}
// Internal - no JSDoc needed
function normalize(data) {
// Iterate quickly here
return Object.keys(data).reduce(/* ... */);
}
The exported updateUser gets full JSDoc because it's your public promise. The internal normalize helper? Keep it flexible.
Key Takeaway: Type your public exports thoroughly with JSDoc, but leave internal implementation code untyped to balance safety with development speed.