CesiumGS / cesium

An open-source JavaScript library for world-class 3D globes and maps :earth_americas:
https://cesium.com/cesiumjs/
Apache License 2.0
12.98k stars 3.5k forks source link

Evaluate eslint-plugin-jsdoc #10815

Open sanjeetsuhag opened 2 years ago

sanjeetsuhag commented 2 years ago

To help enforce consistency in how we use JSDoc in the CesiumJS codebase, we should evaluate the eslint-plugin-jsdoc. It seems like it is actively maintained and fairly popular. If we like it enough, we should also consider it for eslint-config-cesium.

jjhembd commented 1 year ago

After the work by @onsummer in #11080, this plugin could be a good way to ensure consistency going forward.

The default rules might require too much change at once. We could phase the implementation as follows:

First PR

  1. Add the dependency
  2. Update .eslintrc.json and .eslintrc.json
  3. Enable the check-types rule only, setting it to "error"
  4. Confirm that the results match what we implemented in #11080

Later PRs

Test more of the recommended rules, and enable the ones that give the best return on effort. We could prioritize as follows:

  1. Rules that don't require much change to our docs. These will enforce existing doc style going forward
  2. Rules that flag behavior that can be auto-corrected with the --fix option. For example, check-tag-names to replace @return with @returns
  3. Rules that flag serious errors like invalid tag names