Generate Node.js API Documentation From Reviewed JSDoc

A coding assistant can describe a function in JSDoc comments, which a generator can turn into readable API documentation. Verify the behavior from source and tests before you publish what the assistant wrote.

Worked example

Reviewable documentation for a small conversion function

/**
 * Answers a duration in seconds for a whole number of minutes.
 * @param {number} minutes - Whole minutes, zero or greater.
 * @returns {number} Duration in seconds.
 * @throws {RangeError} If minutes is not a nonnegative integer.
 * @example
 * toSeconds(3); // 180
 */
export function toSeconds(minutes) {
  if (!Number.isInteger(minutes) || minutes < 0) {
    throw new RangeError("Expected whole nonnegative minutes");
  }
  return minutes * 60;
}

Steps

  1. Give the coding assistant the function and relevant tests. Ask it to draft JSDoc for parameter types, return type, errors, and an example using only behavior shown in those files.
  2. Keep the function unchanged while you review its comments. Put the example in duration.js and, after installing JSDoc in your project, run npx jsdoc duration.js -d docs-preview.
  3. Open docs-preview/index.html and check the output for the exported function. Run the input and failure examples as ordinary tests before sharing the docs.

What to check

  • Check that the docs describe 0 as valid and 1.5 as invalid. Remove any guarantee about rounding or string conversion that the implementation does not make.
  • A successful documentation build proves the syntax was usable. Exercise the real function to verify the documented behavior.

References