To the extent reasonable, we should enforce that all functions and top-level symbols of a file have preceding JSDoc. The goal here is in making helping to make clear the purpose of a function, both to the original author and to future maintainers.
It extendsrequire-jsdoc, so may be subject to future deprecation removal
Other exemptions aren't neatly covered by eslint-plugin-require-jsdoc-except
Example: Providing a function as an object property option needn't require documentation. Or, at least, it may be confusing to document the option rather than a named function which describes the intent of the callback handler.
There are a huge number of existing violations (over 2000, even after component API exemption).
Recommendation:
Make it an error, but add eslint-disable-next-line inline adjacent to each violation (automation may help), with a "Disable reason" clarifying that there is no legitimate reason for it to be disabled, and that it should be corrected at the earliest opportunity.
Don't make it a warning. In my experience, ESLint warnings are almost always ignored, and do not result in a positive trend toward resolving issues.
swissspidy
commented
5 years ago
Previously: #6341, #4506, #4245
To the extent reasonable, we should enforce that all functions and top-level symbols of a file have preceding JSDoc. The goal here is in making helping to make clear the purpose of a function, both to the original author and to future maintainers.
Implementation Notes:
require-jsdoc.@wordpress/element(React) component API, as the documentation would not be very useful for methods likerendereslint-plugin-require-jsdoc-exceptallows for exceptions by namerequire-jsdoc, so may be subject to future deprecation removaleslint-plugin-require-jsdoc-excepteslint-disable-next-lineinline adjacent to each violation (automation may help), with a "Disable reason" clarifying that there is no legitimate reason for it to be disabled, and that it should be corrected at the earliest opportunity.