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
- 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.
- 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.
- 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.