new rule prefer-jsdoc

[tjx666]

Motivation

jsdoc can provide useful documentation with IDE integration.

Current behavior

case one: object property

const person = {
    name: 'ly',
    // some description op top of property
    age: 18, // some description after property
};

case 2: typescript interface, should also work for type, enum

interface Options {
    // default value is ['.js', '.ts']
    extensions: String[]; // default value is ['.js', '.ts']
}

case 3: function

// compute sum of two numbers
function add(a, b) {
    
}

Desired behavior

all single comments above should be replaced with jsdoc

Alternatives considered

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[thernstig]

@tjx666 @brettz9 isn't this what https://eslint.org/docs/latest/rules/multiline-comment-style does already? That could be enforced there.

[brettz9]

@thernstig : While that might make sense as a host for the behavior, that rule looks like it converts line comments (and only multiple consecutive ones) to block comments (including the conventionally asterisked lines) but doesn't convert any comments to JSDoc-style comments (which must have the 2 asterisks at the beginning).

[tjx666]

block comment:

/* this is a
block 
comment */

jsdoc: start withs /**, and will be parsed by typescript:

/**this is
jsdoc
comment */

[brettz9]

@tjx666 : I'd suggest asking for this feature within multiline-comment-style even though that rule doesn't offer the option currently

[tjx666]

@brettz9 I think this rule is complex enough and I can't find rule multiline-comment-style

[brettz9]

I'm speaking about ESLint's own rule. See https://eslint.org/docs/latest/rules/multiline-comment-style

[brettz9]

I'm suggesting requesting this feature from ESLint itself.

[tjx666]

Seems eslint self doesn't accept feature other than ECMAScript new syntax

[brettz9]

Ok, yeah, thanks for checking.

[brettz9]

Filed #1256 . Care to take a look, @tjx666 ?

Note that it doesn't currently work for comments after the structure--only before, and you have to specify contexts if you want it to apply in more than regular functions/methods.

[github-actions]

🎉 This issue has been resolved in version 48.6.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[brettz9]

I've noted that the new rule is experimental (and it's not under recommended), but it now includes options to check before, after, or before and after. I expect the rule (or the @es-joy/jsdoccomment code it depends upon) will need some further tweaking, but it, as per the tests, should handle the use cases mentioned.