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

[aduth]

I'm going to close this. It was impractical back in 2019 and I expect would be exponentially more difficult these days. AI could assist here, though I think it's worth revisiting the merits of why we wanted this back in 2019 and how we would think about this today:

• Documenting typings through JSDoc is superseded these days by the expectation to author in TypeScript
• We have some mechanisms for surfacing missing documentation in areas where documentation is relied on by contributors and AI agents:
  • Automated package documentation includes an "Undocumented declaration" message in output
  • For documentation surfaced to Storybook, we recently added testing to require that components and their props have documentation extractable from their JSDoc comments

If we were ever to revisit this, we also have ESLint bulk suppressions available which could make it easier to enforce a new rule while permitting existing legacy issues.