-
-
Notifications
You must be signed in to change notification settings - Fork 153
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Redesign option for require-jsdoc #384
Comments
While they are indeed all functions, projects often use them for distinct purposes. For example, some use arrow functions only within contexts like Likewise do some use function expressions (or arrow functions) to denote functions for nested utilities that may be of less significance then those used as declarations. While I would support additional shorthand options, I think we should preserve the old distinctive options for the above reason. |
The schema you suggested seemed prone to abuse, it encourages people to write function in different syntax as a way to circumvent this rule. It is not a good idea to hint the significance of a function by writing it in different syntax. There is no clear map between the chosen syntax and the significance of the function. The syntax chosen is usually decided by other considerations. In case like
Doing so is a shotgun that affects many other cases: // ignore `FunctionExpression` because of this case:
const utils = {
f(){},
g(){}
}
// will also ignore these cases:
module.exports = function f() {}
module.exports = { f() {} }
exports.f = function f() {}
This is a non-issue since function used like callback are ignored by this rule. |
You speak about linting rules as though they are always meant to catch bad guys sneaking in bad code, whereas projects often seek it to legitimately make their lives easier. They simply don't want their code bloated with what they view as unnecessary comments. The interest in #192 on restricting to public exports is one example of this, but not the only one.
That is what is done with https://eslint.org/docs/rules/prefer-arrow-callback though, as you note, it may not be affected here. However, as far as your comment about being "prone to abuse", would that not, per your view, encourage people to circumvent writing documented functions by stuffing everything into an inline callback rather than having the callback be defined at a higher level (e.g., outside of a loop)? If one wishes to be more exacting (or draconian and distrustful as the case may be),
I agree it can be decided by preference, and that is why it is good to let projects prefer how they do it, including allowing them to enforce a mapping to significance. You do have a good point on the use of function expressions on object literals, but I think this argues for more control (e.g., the context of those expressions), rather than less. Likewise with exports (though in some projects and certain cases, it may instead be preferred to prohibit such usage entirely; for example, a project prohibiting anonymous default exports (see https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-anonymous-default-export.md for an already-existing ES6 import version, though the same could be made for CommonJS exports) along with enforcing the |
I think one thing we're both missing here is the fact that Selectors (driven within eslint by For example, esquery already has a shortcut for module.exports = function f() {}
module.exports = { f() {} }
exports.f = function f() {} Or if one preferred, these expressions can also be quite explicit, so for the first one, for example, one could target only this particular syntax with:
...or the second type with the following (could probably be shortened):
...or the third type with:
(Expressions as usual derived with help from https://astexplorer.net/ .) |
The option for
require-jsdoc
is hard to use. It requires knowledge of ESTree. And it is not useful for this rule to make distinction betweenFunctionDeclaration
,FunctionExpression
, andArrowFunctionExpression
, conceptually there are just functions, whether it is arrow function does not affect whether it needs jsdoc comment.A more user friendly option will be:
This would be a breaking change.
Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.
The text was updated successfully, but these errors were encountered: