fix: re-enable jsdoc checks

[cwillisf]

Resolves

• Resolves Enable the jsdoc/valid-types rule #20 (again)

Proposed Changes

Add eslint-plugin-jsdoc to the new configuration. Specifically, the plugin's recommended configuration is enabled generally and then overridden by the plugin's recommended TypeScript configuration for TypeScript files.

Reason for Changes

I forgot to add eslint-plugin-jsdoc when creating our new configuration, even though it's present in the legacy configurations. This change re-adds the plugin and configures it for better interaction with TypeScript.

Test Coverage

Tested locally on this repository. I also created some temporary TypeScript files to test those rules.

[Copilot]

Pull Request Overview

This PR re-enables JSDoc checks by adding eslint-plugin-jsdoc to the configuration and enabling its recommended rules, including specific overrides for TypeScript files.

• Updated the Prettier configuration's JSDoc comment for clarity.
• Imported eslint-plugin-jsdoc and integrated its recommended configurations and custom rules in the ESLint configuration.

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
lib/prettier.mjs	Updated JSDoc comment to include a more descriptive return annotation.
lib/eslint.mjs	Added eslint-plugin-jsdoc import and integrated its recommended configurations and custom rule settings for better interaction with TypeScript.

[cwillisf]

I ran this against some of the NGP JS & TS code, and the results generally seemed reasonable.

[cwillisf]

I'm a little concerned this may be too much of a hassle, even with publicOnly enabled, so I'm open to feedback.

[georgyangelov]

I guess the trouble with publicOnly is that it can't know whether something is exported from the package, or is exported from a module but otherwise private in the package 🤔

Maybe make it configurable? I see this being beneficial for library packages (scratch-editor/*, scratch-platform/scratch-web-shared), while for scratch-web it might not make as much sense as it's not being consumed by other code.

Also I would say for TS files we should make it so that type annotations in JSDoc are not mandatory - TS does a better job of that and they'll go out of sync pretty quickly if we have to duplicate them.

I've generally found that if you have TS and name your functions/components/types appropriately - JSDocs rarely provide much in addition. They are useful in cases where the component/function does complicated logic that needs explanation and examples, but that's hard to enforce automatically 🤔

[cwillisf]

Maybe make it configurable? I see this being beneficial for library packages (scratch-editor/*, scratch-platform/scratch-web-shared), while for scratch-web it might not make as much sense as it's not being consumed by other code.

Yeah, that's probably best. I'll remove jsdoc/require-jsdoc from this config. A particular project or library can always enable it locally, if desired.

Also I would say for TS files we should make it so that type annotations in JSDoc are not mandatory - TS does a better job of that and they'll go out of sync pretty quickly if we have to duplicate them.

Good news on this front! With this configuration, redundant JSDoc type annotations are forbidden in TS. In other words, after removing jsdoc/require-jsdoc, this configuration will permit three cases:

• JS/TS with no JSDoc at all
• JS with JSDoc that includes type annotations (@param {string} foo The thing with the stuff.)
• TS with JSDoc that excludes redundant type annotations (@param foo The thing with the stuff.)

I included the word "redundant" because there are a few situations in TS where JSDoc type annotations are not redundant and not forbidden. See docs: https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-types.md

[georgyangelov]

Nice!