Enhancement: valid-jsdoc: Allow the omission of @returns when @chainable tag specified

We make use YUIdoc documentation format, and have found the valid-jsoc rule fine for checking the yuidoc, one small niggle is that we make use of the @chainable tag and that implies that a @return tag is not necessary.

I understand this is not really standard jsdoc variant so is a controversial request. In support of my request is that I see some people are keen to support this syntax in jsdoc and are already using this syntax in the wild.

The version of ESLint you are using 3.0.1 The rule you want to change valid-jsoc The code you want to be flagged as correct

/* eslint valid-jsdoc: [“error”, { “allowChainable”: true }] */

/**
 * Renders this view …
 * @chainable
 */
function render() {
     // do stuff
     return this; 
}

What happens when the rule is applied to the code without your change Missing JSDoc @returns for function. (valid-jsdoc)

[nzakas]

In order to avoid hardcoding YUIDoc-specific logic into the rule, we could consider adding an option for tag synonyms. Something like:

valid-jsdoc: ["error", { synonyms: { "return": "chainable" } { ]

I’d champion such a change as I think it will make other instances of similar problems easier.

[kaicataldo]

Understand the confusion. By “reaching consensus” I mean the process of accepting the issue (which the team has decided requires a champion and three upvotes from the team). Can definitely make that clearer in the future.

We’ve found that issues that get buried in the backlog without getting accepted end up getting lost (as can be evidenced by the lack of discussion here). Keeping our issues backlog manageable is necessary for keeping the project moving forward, both for us maintainers and also for our contributors.

Feel free to open a new issue with your proposal - chances are much higher it’ll get some attention when it’s not multiple pages deep into our issues list!