search

gajus / eslint-plugin-jsdoc

JSDoc specific linting rules for ESLint.
Other
1.08k stars 155 forks source link

Require jsdoc only for everything exported from a specific file #1200

Closed ashwinGokhale closed 5 months ago

ashwinGokhale commented 5 months ago

Motivation

We have an Nx monorepo where the public API for libraries are defined in a single file: libs/path/to/lib/src/index.ts. The publicOnly option for the jsdoc/require-jsdoc rule does not allow me to specify where the public API is defined.

Current behavior

The publicOnly option only checks if it is exported in general.

Desired behavior

The publicOnly option lets me specify a list of files that define my public API and only checks the ones explicitly exported from those files.

Alternatives considered

brettz9 commented 5 months ago

To apply ESLint rules like eslint-plugin-jsdoc to particular files, you can use overrides, or if you are using the new flat config, just add a new top-level object with its own files array.

Closing as this should resolve, though feel free to comment further as needed.

ashwinGokhale commented 5 months ago

Hi @brettz9 adding the overrides for only the src/lib/index.ts file does not solve my problem. Here is a small example to show to problem. In this example the foo function has an error (which is expected), but the a function does not. I would expect the a function to have an error because I export it from src/lib/index.js.

brettz9 commented 5 months ago

ESLint is, unfortunately, only aware of a single file at a time.

Perhaps documenting the export statement itself would work for you (e.g., adding ExportNamedDeclaration to the contexts and requiring a comment block above that)?

ashwinGokhale commented 5 months ago

@brettz9 That won't work either because it doesn't catch export * syntax. Is there a way to specify the public API files in the publicOnly option and cross check with the exports in those files?

brettz9 commented 5 months ago

@brettz9 That won't work either because it doesn't catch export * syntax.

We can see why ExportAllDeclaration may not be working. I wouldn't expect that to be too difficult of a problem.

Is there a way to specify the public API files in the publicOnly option and cross check with the exports in those files?

ESLint only lints a file at a time, so, no, not really. We would have to do the linting of the discovered files ourselves. It might be possible with the ESLint class, but I'm not inclined to do such work myself.