Eslint-plugin-jsdoc: Option to require a docblock for the file?

[tdmalone]

A lot of the focus of docblocks is on functions, so this may not be a common need, but I'm wondering whether it might be worth an option to require a docblock at the top of the file?

There is at least one jsdoc tag that is specifically for use in a file docblock, so the concept is at least supported.

[bary12]

I would like to see us add a new rule for this, maybe jsdoc/require-file-overview. It would not fit our current architecture which does only search through function docs, but it can be done separately. Maybe I can open a pull request for this in a few days.

Edit July 2019: more than a few days have passed and I haven't done it.

[gajus]

@bary12 Are you available to a PR for this?

[bary12]

@gajus Unfortunately no

[brettz9]

I was thinking of tweaking my current PR for this (#464), to allow a whitelist of other tags to check since some other tags such as the following might, in at least some cases, be desirable as one per file (or 1+ per file): @license, @copyright, @author, @module and possibly @exports.

I'd also like to allow this whitelist to tweak the behavior per tag since the rule as it is currently not only checks that a given tag is present, but also currently checks that there are no duplicates and that it is not preceded by any non-comment code (a project might wish to allow some tags like @license to occur more than once per file, and not all need be in a prefatory context, e.g., @author attached to a particular function or @exports).

@license would be particularly interesting if supported, if used in conjunction with the check-values rule, with the allowedLicenses or licensePattern options, one could enforce that a license not only be present but also be of a particular whitelisted type (e.g., to check that one's project only consisted of say MIT and X11, or whatever).

Update: I've now filed #469 for this purpose.

[gajus]

:tada: This issue has been resolved in version 18.7.0 :tada:

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot :package::rocket: