Course contentsShow
← JavaScript
Lesson 2646 of 2,72353. Type Safety Without TypeScriptFree lesson

JSDoc for Public API Surfaces Only

Documenting exported functions and classes while leaving internal code untyped for rapid iteration.

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.