Maintain precise and accurate documentation through both JSDoc annotations and explanatory comments. Ensure all technical documentation matches the actual implementation, avoiding inconsistencies between code and documentation.
Key practices:
Keep JSDoc parameter and return types strictly accurate
Avoid default values in JSDoc to prevent inconsistencies
Document unusual patterns or complex implementations
Include clear examples for non-obvious functionality
Example:
```javascript
/**
Format help text for printing.
@param {string} longOption - long option name e.g. ‘foo’
@param {object} optionConfig - option config from parseArgs({ options })
@returns {string} formatted help text for printing
// returns ‘–foo help text'
*/
function formatHelpTextForPrint(longOption, optionConfig) {
// Implementation using unusual pattern - explain why
if (isSpecialCase(optionConfig)) {
// Document why this special case exists
// and how it affects the output
}
// ... rest of implementation
}
