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.