chore: Lint TsDoc. #6353
chore: Lint TsDoc. #6353
Conversation
This reverts commit d6d8656.
|
The remaining 11 warnings should probably all be fixed. They are related to missing or incorrect jsdoc comments. I will take a look at those tomorrow but the rest of this can be reviewed. |
|
p.s. thank you to Beka for the regex wizardry |
.eslintrc.json
Outdated
| "parser": "@typescript-eslint/parser", | ||
| "parserOptions": { | ||
| "project": "./tsconfig.json", | ||
| "tsconfigRootDir": ".", | ||
| "ecmaVersion": 2020, | ||
| "sourceType": "module" | ||
| }, | ||
| "extends": ["plugin:@typescript-eslint/recommended"], | ||
| "extends": ["plugin:@typescript-eslint/recommended", "plugin:jsdoc/recommended"], |
There was a problem hiding this comment.
Changed this, but for future reference
a. this file is not actually linted, and we don't have rules for json files
b. if we follow the rules for js files, line length is 100 and this was only 90
if we want to consistently lint this file we'd need to set that up.
|
I'm going to assign this to Rachel to re-review in my absence. |
cpcallen
added
component: TypeScript
PR: chore
|
LGTM once you fix the line length issue Christopher pointed out--I'm satisfied with your reasons for leaving the other things as-is. |
maribethb
dismissed
cpcallen’s stale review
Addressed comments, and got fenichel's approval while christopher is ooo
The basics
npm run formatandnpm run lintThe details
Resolves
Resolves #6338
Proposed Changes
eslint-plugin-jsdocplugin and configures some rules for it. Only on TS files.require-paramrule as it breaks for functions that usethis: check-param-names - False positives with TypeScript "this" parameter gajus/eslint-plugin-jsdoc#904 (this caused the CI failures as it broke closure. also i reverted the change that automatically added the extra@param thisbut it wasn't a clean revert so sorry for the messy git history)check-param-namerule for same reason. if we ever re-enable this rule if above issue is fixed, we should most likely keepcheckDestructuredas false. we could consider changing how we document destructured params but afaict TsDoc provides no official guidance so i don't see a need to enforce a specific dialect different than we have.@suppress {warningName}made sense even thoughwarningNameis not a type in this case. when we remove closure we should both re-enable these rules and remove the closure-specific annotations (e.g. nocollapse, dict, unrestricted, etc)@fileoverviewcomment blocks. I checked over 100 of them and they were all identical copies of either the class or namespace comment (right above it in most cases).@fileoverviewis not a supported tag and these were worthless comments anyway.@returnto@returnsand adding a blank line after the description in a tsdoc block. reverted this change once, not cleanly, and did it again. sorry@structwhich is not supported and doesn't do anything anyways because they were on es6 classes which are struct by default.No lint warnings!
Behavior Before Change
No linting on TsDoc.
Behavior After Change
Linting on TsDoc.
Reason for Changes
Cleaning up the TsDoc will improve the API Extractor output.
Additional Information
Microsoft provides an eslint plugin for tsdoc (
eslint-plugin-tsdoc) but it works in the most annoying way I can think of - instead of separating the things it checks for into individual rules that you can then disable or modify as you wish, it puts all the checks into one rule called tsdoc/syntax so you cannot enable only some of the checks. it's very all or nothing.and even though they made the actual TsDoc parser accept parameter docs that don't have hyphens, the lint rule still enforces that you must have hyphens and there is no way to turn that off. VS Code, which MS also makes, doesn't add the hyphens in the autogenerated docs. so this is one area where it seems like the community disagrees with the TsDoc spec and they somewhat accepted that.
anyway you cannot incrementally fix the lint errors like i'm doing with the other lint rules, using the
eslint-plugin-tsdoc. and additionally there is no rule that checks that each public function has tsdoc. instead that logic is built into api extractor for some reason.so instead of dealing with that plugin, i'm just using
eslint-plugin-jsdocwhich you can configure to typescript "flavor". this is the same plugin we use in samples. it is highly configurable. the default settings do not perfectly match the TsDoc spec (e.g. there are some tags that TsDoc doesn't recognize that the plugin is fine with) but overall it should be easier to use and adapt how we want it.