Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Testing: Add rule to enforce existence of JSDoc #15193

Open
aduth opened this issue Apr 25, 2019 · 1 comment
Open

Testing: Add rule to enforce existence of JSDoc #15193

aduth opened this issue Apr 25, 2019 · 1 comment
Labels
[Tool] Docgen /packages/docgen [Type] Automated Testing Testing infrastructure changes impacting the execution of end-to-end (E2E) and/or unit tests. [Type] Task Issues or PRs that have been broken down into an individual action to take

Comments

@aduth
Copy link
Member

aduth commented Apr 25, 2019

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
  • 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.
@aduth aduth added [Type] Task Issues or PRs that have been broken down into an individual action to take [Type] Developer Documentation Documentation for developers [Type] Automated Testing Testing infrastructure changes impacting the execution of end-to-end (E2E) and/or unit tests. labels Apr 25, 2019
@aduth aduth mentioned this issue Apr 25, 2019
4 tasks
@swissspidy
Copy link
Member

See also #13741

@aduth aduth changed the title Testing: Add rule to enforce JSDoc Testing: Add rule to enforce existence of JSDoc Nov 12, 2019
@DaisyOlsen DaisyOlsen added [Tool] Docgen /packages/docgen and removed [Type] Developer Documentation Documentation for developers labels Feb 21, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Tool] Docgen /packages/docgen [Type] Automated Testing Testing infrastructure changes impacting the execution of end-to-end (E2E) and/or unit tests. [Type] Task Issues or PRs that have been broken down into an individual action to take
Projects
None yet
Development

No branches or pull requests

3 participants