Testing: Add rule to enforce existence of JSDoc

[aduth]

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:

• ESLint includes a rule require-jsdoc.
  1. However, it is deprecated and slated for removal in the next major version (along with all JSDoc support)
  2. This was used in the original Add WordPress JSDoc ESLint configuration #4245
• Not all symbols should be documented:
  • It would be reasonable to exempt @wordpress/element (React) component API, as the documentation would not be very useful for methods like render
  • A separate project eslint-plugin-require-jsdoc-except allows for exceptions by name
    • This is sufficient for exempting component API
    • It extends require-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.
      • Prior art: Framework: Define all ESLint rules as errors Automattic/wp-calypso#8562
      • Alternative: https://www.npmjs.com/package/eslines

[swissspidy]

See also #13741