Description

Triggered by @saramarcondes in #28568 (comment):

It's just that the JSDoc parser that is used for our JSDoc linter doesn't understand complex types like function signatures and imports. If you check out other parts of the code based that are typed you'll notice that they're littered with /* eslint-disable jsdoc/valid-types */. This is unfortunate but I'm not sure what we can do about it other than disable the rule (but then we might start getting actually invalid types committed... who knows.

have y'all given any thought to disabling that rule? jsdoc/no-undefined-types is another that tends to give us trouble when typing JavaScript files.

Solution based on the proposal from @sirreal in #28568 (comment):

Looking at include in tsconfig is going to be complex, I believe. We might need to inspect files, include, and exclude. I may have a good idea for an alternative heuristic 🙂

Our convention is to write types to the dist-types for publish. This requires a field to be added to the package.json when we're ready to publish the types, and we're only doing that when packages are fully typed. We may be able to check package.json for the presence of this, and disable the JSDoc type linter if it's present:

gutenberg/packages/a11y/package.json

Line 26 in 92baa9b

"types": "build-types",

This PR relaxes JSDoc validation for packages typed with TypeScript. It's redundant since TypeScript does the validation already, so it only enforces folks to disable the rule when JSDoc doesn't understand TS type.

How has this been tested?

npm run lint-js

Types of changes

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code follows the accessibility standards.
• My code has proper inline documentation.
• I've included developer documentation if appropriate.
• I've updated all React Native files affected by any refactorings/renamings in this PR.