Always ensure documentation accurately represents the actual code behavior and implementation details. Include important contextual information such as:
When documenting APIs, verify that your descriptions match the actual implementation rather than the intended design. For example, if a function behaves differently than originally designed, update the documentation to reflect the actual behavior:
// INCORRECT DOCUMENTATION
// `validateStatus` defines whether to resolve or reject the promise for a given
// HTTP response status code. If `validateStatus` returns `true` (or is set to `null`
// or `undefined`), the promise will be resolved; otherwise, the promise will be rejected.
// CORRECT DOCUMENTATION
// `validateStatus` defines whether to resolve or reject the promise for a given
// HTTP response status code. If `validateStatus` returns `true` (or is set to `null`),
// the promise will be resolved; otherwise, the promise will be rejected.
For deprecated features, clearly indicate:
~~Concurrency~~
Deprecated. Use `Promise.all` to replace them.
Keep documentation concise by consolidating related code examples when possible.
Enter the URL of a public GitHub repository