Add JSDoc lint rules to follow style guide #48

bryan-hoang · 2023-08-27T21:43:32Z

To enforce the addition of file overview comments & JSDoc comments on
exported symbols.

wiwichips · 2023-09-14T14:44:58Z

Unrelated to this MR (also present on main), but this rule causes an error for me: '@distributive/brace-style': 'warn'

Oops! Something went wrong! :(

ESLint: 8.40.0

TypeError: Cannot read properties of undefined (reading 'loc')
Occurred while linting /home/will/git/eslint-config/file2.js:2
Rule: "@distributive/brace-style"
    at areTokensOnSameLine (/home/will/git/eslint-config/node_modules/@distributive/eslint-plugin/lib/rules/brace-style.js:35:49)
    at VariableDeclaration (/home/will/git/eslint-config/node_modules/@distributive/eslint-plugin/lib/rules/brace-style.js:60:18)
    at ruleErrorHandler (/home/will/git/eslint-config/node_modules/eslint/lib/linter/linter.js:1049:28)
    at /home/will/git/eslint-config/node_modules/eslint/lib/linter/safe-emitter.js:45:58
    at Array.forEach (<anonymous>)
    at Object.emit (/home/will/git/eslint-config/node_modules/eslint/lib/linter/safe-emitter.js:45:38)
    at NodeEventGenerator.applySelector (/home/will/git/eslint-config/node_modules/eslint/lib/linter/node-event-generator.js:297:26)
    at NodeEventGenerator.applySelectors (/home/will/git/eslint-config/node_modules/eslint/lib/linter/node-event-generator.js:326:22)
    at NodeEventGenerator.enterNode (/home/will/git/eslint-config/node_modules/eslint/lib/linter/node-event-generator.js:340:14)
    at CodePathAnalyzer.enterNode (/home/will/git/eslint-config/node_modules/eslint/lib/linter/code-path-analysis/code-path-analyzer.js:795:23)

^ if I remove the line, it works. Guessing I'm missing some install?

bryan-hoang · 2023-09-14T14:47:47Z

Unrelated to this MR (also present on main), but this rule causes an error for me: '@distributive/brace-style': 'warn'

Oops! Something went wrong! :(

ESLint: 8.40.0

TypeError: Cannot read properties of undefined (reading 'loc')
Occurred while linting /home/will/git/eslint-config/file2.js:2
Rule: "@distributive/brace-style"
    at areTokensOnSameLine (/home/will/git/eslint-config/node_modules/@distributive/eslint-plugin/lib/rules/brace-style.js:35:49)
    at VariableDeclaration (/home/will/git/eslint-config/node_modules/@distributive/eslint-plugin/lib/rules/brace-style.js:60:18)
    at ruleErrorHandler (/home/will/git/eslint-config/node_modules/eslint/lib/linter/linter.js:1049:28)
    at /home/will/git/eslint-config/node_modules/eslint/lib/linter/safe-emitter.js:45:58
    at Array.forEach (<anonymous>)
    at Object.emit (/home/will/git/eslint-config/node_modules/eslint/lib/linter/safe-emitter.js:45:38)
    at NodeEventGenerator.applySelector (/home/will/git/eslint-config/node_modules/eslint/lib/linter/node-event-generator.js:297:26)
    at NodeEventGenerator.applySelectors (/home/will/git/eslint-config/node_modules/eslint/lib/linter/node-event-generator.js:326:22)
    at NodeEventGenerator.enterNode (/home/will/git/eslint-config/node_modules/eslint/lib/linter/node-event-generator.js:340:14)
    at CodePathAnalyzer.enterNode (/home/will/git/eslint-config/node_modules/eslint/lib/linter/code-path-analysis/code-path-analyzer.js:795:23)

^ if I remove the line, it works. Guessing I'm missing some install?

That's fixed by Distributive-Network/eslint-plugin#1 😅. You'll need to link it in to test the config properly. Given that this PR is specifically for the JSDoc rules, it's fine disabling the broken plugin rule for now.

Ideally, the parsing PR lands to make it easier to review this PR.

wiwichips · 2023-09-14T15:20:34Z

@bryan-hoang

playing around with it, can't find any problems

I suppose it doesn't necessarily "enforce the addition of [...] JSDoc comments on
exported symbols". For example this doesn't report any errors

'use strict';
/**
 * @file file.js
 * @author will
 * @date somedate
 */

const a = 0;

exports.imExported = function imExported(arg)
{
  return arg+a;
}

the imExported symbol is exported without a JSdoc

I assume this is fine and probably impossible in eslint anyways - please correct me if I'm confused about anything

otherwise MR looks good!

bryan-hoang · 2023-09-19T13:40:09Z

@bryan-hoang

playing around with it, can't find any problems

I suppose it doesn't necessarily "enforce the addition of [...] JSDoc comments on exported symbols". For example this doesn't report any errors
'use strict';
/**
 * @file file.js
 * @author will
 * @date somedate
 */

const a = 0;

exports.imExported = function imExported(arg)
{
  return arg+a;
}
the imExported symbol is exported without a JSdoc

I assume this is fine and probably impossible in eslint anyways - please correct me if I'm confused about anything

otherwise MR looks good!

@wiwichips Thanks for the catch! It looks like I missed an option that's needed to enable checking for those exports.

I've also added a rule to require a description on empty comment blocks so that just running ESLint with the --fix option won't just make the errors go away.

wiwichips

will@bestia:~/git/eslint-config ➡ npx eslint file.js 

/home/will/git/eslint-config/file.js
  10:22  error  Missing JSDoc comment  jsdoc/require-jsdoc

✖ 1 problem (1 error, 0 warnings)
  1 error and 0 warnings potentially fixable with the `--fix` option.

will@bestia:~/git/eslint-config ➡ npx eslint file.js  --fix

/home/will/git/eslint-config/file.js
  10:1  error  Missing JSDoc block description  jsdoc/require-description

✖ 1 problem (1 error, 0 warnings)

Awesome, beautiful errors now when trying to export symbols without js docs and it does not "fix it" by just adding comments above the things and acting like thats fine

LGTM

eroosenmaallen

Love it!
Is there a way it (the JSDoc plugin) can catch people using the VSCode import() syntax that keeps breaking our docs generation?

bryan-hoang · 2023-09-19T17:44:24Z

Love it! Is there a way it (the JSDoc plugin) can catch people using the VSCode import() syntax that keeps breaking our docs generation?

From perusing the plugin's docs/issues, it doesn't look like it supports linting the typedef-import plugin from better-docs that we use. But after reading through jsdoc/jsdoc#1645, it seems like using https://github.com/polyforest/jsdoc-tsimport-plugin/ instead could net us the best of both worlds. A working build w/ jsdoc & being recognized by editor tooling (i.e., JS/TS LSP stuff for VS Code & friends).

To enforce the addition of file overview comments & JSDoc comments on exported symbols.

Some properties are unnecessary/unused. Others can be updated to target latest EMCAScript code. A brace was reformatted to follow the brace style guide.

bryan-hoang · 2023-09-22T19:15:13Z

@eroosenmaallen I've opened an MR on the DCP repo as a proof of concept for #48 (comment), as I don't see a quick way of getting ESLint w/ the JSDoc plugin to understand this requirement as a lint rule.

bryan-hoang · 2023-09-27T18:12:33Z

@eroosenmaallen I've opened an MR on the DCP repo as a proof of concept for #48 (comment), as I don't see a quick way of getting ESLint w/ the JSDoc plugin to understand this requirement as a lint rule.

Given the above, I think this PR can be merged as is since it doesn't look like a blocking comment.

bryan-hoang added the enhancement New feature or request label Aug 27, 2023

bryan-hoang self-assigned this Aug 27, 2023

bryan-hoang force-pushed the feature/jsdoc-config branch from 194dd62 to 37415d4 Compare August 28, 2023 00:26

bryan-hoang requested a review from Xmader August 28, 2023 00:47

bryan-hoang force-pushed the feature/jsdoc-config branch from 37415d4 to efb7229 Compare August 28, 2023 00:53

bryan-hoang requested review from wiwichips and removed request for Xmader September 6, 2023 13:08

bryan-hoang force-pushed the feature/jsdoc-config branch from efb7229 to 2a7efe2 Compare September 19, 2023 13:41

wiwichips approved these changes Sep 19, 2023

View reviewed changes

bryan-hoang requested a review from eroosenmaallen September 19, 2023 15:39

eroosenmaallen approved these changes Sep 19, 2023

View reviewed changes

bryan-hoang added 3 commits September 22, 2023 09:17

feat: add jsdoc lint rules for style guide

f1de50e

To enforce the addition of file overview comments & JSDoc comments on exported symbols.

docs(.eslintrc.js): add missing file overview comment

1ef5ac5

chore(.eslintrc.js): clean up config props

dee46ec

Some properties are unnecessary/unused. Others can be updated to target latest EMCAScript code. A brace was reformatted to follow the brace style guide.

bryan-hoang force-pushed the feature/jsdoc-config branch from 2a7efe2 to dee46ec Compare September 22, 2023 13:18

bryan-hoang requested a review from eroosenmaallen September 26, 2023 13:13

bryan-hoang merged commit 81d8637 into main Sep 27, 2023

bryan-hoang deleted the feature/jsdoc-config branch September 27, 2023 18:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add JSDoc lint rules to follow style guide #48

Add JSDoc lint rules to follow style guide #48

bryan-hoang commented Aug 27, 2023 •

edited

Loading

wiwichips commented Sep 14, 2023 •

edited

Loading

bryan-hoang commented Sep 14, 2023 •

edited

Loading

wiwichips commented Sep 14, 2023 •

edited

Loading

bryan-hoang commented Sep 19, 2023 •

edited

Loading

wiwichips left a comment •

edited

Loading

eroosenmaallen left a comment

bryan-hoang commented Sep 19, 2023

bryan-hoang commented Sep 22, 2023

bryan-hoang commented Sep 27, 2023 •

edited

Loading

Add JSDoc lint rules to follow style guide #48

Add JSDoc lint rules to follow style guide #48

Conversation

bryan-hoang commented Aug 27, 2023 • edited Loading

wiwichips commented Sep 14, 2023 • edited Loading

bryan-hoang commented Sep 14, 2023 • edited Loading

wiwichips commented Sep 14, 2023 • edited Loading

bryan-hoang commented Sep 19, 2023 • edited Loading

wiwichips left a comment • edited Loading

Choose a reason for hiding this comment

eroosenmaallen left a comment

Choose a reason for hiding this comment

bryan-hoang commented Sep 19, 2023

bryan-hoang commented Sep 22, 2023

bryan-hoang commented Sep 27, 2023 • edited Loading

bryan-hoang commented Aug 27, 2023 •

edited

Loading

wiwichips commented Sep 14, 2023 •

edited

Loading

bryan-hoang commented Sep 14, 2023 •

edited

Loading

wiwichips commented Sep 14, 2023 •

edited

Loading

bryan-hoang commented Sep 19, 2023 •

edited

Loading

wiwichips left a comment •

edited

Loading

bryan-hoang commented Sep 27, 2023 •

edited

Loading