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
- @example
- formatHelpTextForPrint(‘foo’, { type: ‘string’, help: ‘help text’ })
- // 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
}