Report @todo's with todo text (and/or for other todo comments), with priority and scope options

[brettz9]

I am interested in writing a rule (as I may have time) which reports todo comments, whether of the jsdoc form (@todo) and/or within normal JavaScript comments (e.g., // todo: , // fixme: , etc.).

Ideally, it would also allow priorities, e.g., // todo (high) or // todo (5), and a rule option to check for these reported priority level(s) or max/min/range (e.g., to report level 1 and 2 priorities but not level 3+).

The format might be customizable and allow one to specify scope as well, e.g., // todo - low (testing): or // todo - 3 (testing), and have an option to check scope independently, so that, e.g., one could report errors related to "performance" but not "testing", etc.

One can pass in a specific rule with options at the eslint command line--even avoiding the eslintrc and solely looking at that rule--so one could, for example, normally allow to-do comments but, when interested, pass a a specific config to the --rule flag on the command line to see a list of what to-dos one has, including those of a given scope and/or priority (and possibly dump them to a file or pass them with --fix to remove them).

A separate but complementary rule might insist on a particular structure to to-do comments (e.g., to ensure they always have a scope and priority). (This rule could be reported always as it would check the validity of to-dos, not complain at their mere existence.) (This rule could be to-do specific, or we might modify match-description to allow other tags besides @param, @returns, etc. to be checked for descriptions of a particular, customizable regex structure.)

The big difference of this proposal from no-warning-comments is that it would implement a feature eslint rejected (eslint/eslint#4409 ), namely showing the actual to-do text within the warning message.

Despite the argument for supposed doctrinal purity in restricting linting to bad code and not dealing with other matters (by that logic, however, eslint-plugin-jsdoc wouldn't even exist), I think pragmatically speaking, it is very useful to actually see what one's to-dos are, and with command line switching, one can leverage eslint to see to-dos sometimes as bad code (since they may signal incomplete code) and sometimes just as documentation worth discovering (to see what to-dos are left).

Since eslint-plugin-jsdoc is related to comments, and as it looks for @todo I figured this might be a suitable home, but I can understand if others feel strongly that it should be separate since it is not limited to jsdoc-block todo comments. @gagus and @golopot, let me know if you think this belongs in eslint-plugin-jsdoc.

Update: Per @golopot's comment, Unicorn has a rule of great use but which doesn't quite cover all use cases. See also sindresorhus/eslint-plugin-unicorn#238 .

[gajus]

What would be the argument against releasing this as a separate plugin eslint-plugin-jsdoc-todo?

I would be happy to link from README.md to this library.

I can totally see a use case for this rule, but thematically it solves a very different problem than what the rest of the plugin is doing (style vs content observation).

[brettz9]

Nothing against it as a separate plugin. Though it does add content observation, it is observing content along with potentially indicating a problem (as with bad jsdoc types or tags, etc.)--i.e., that some important code might not be finished. But yeah, I see it may call for its own plugin.

[brettz9]

I'll close then... Will see if I ever get to it. :)

[chiawendt]

eslint-plugin-unicorn is currently working on it sindresorhus/eslint-plugin-unicorn#238

[brettz9]

I saw that, thanks, but that seems focused on expiring to-dos under certain conditions while mine is focused on reporting text and selecting by scope or priority.