Create require-jsdoc rule

[yfr]

I would like to have a requireJsDoc option for valid-jsdoc. Could be false by default but would be nice to enforce jsDoc at all and then of course the correct jsDoc.

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

[nzakas]

Can you please provide more details for what you are proposing? Is not clear from your description.

[yfr]

Sure!

I want to make sure that every function gets it's jsDoc block. Maybe this would make more sense in it's own rule.

[nzakas]

We need to figure out which functions because you may not, for example, want jadoc on an iife or on an anonymous function passed into another function.

We can probably day function declarations should have jsdoc comments. What else?

[yfr]

Sounds legit. Thought there might be some issues i did not think about.

Maybe we could just start with FunctionDeclaration, FunctionExpression and ArrowFunctionExpression like in valid-jsdoc. These could also be just options.

[nzakas]

I don't think those are granular enough. Consider:

function foo() {
   // most likely want to require for this
}

var foo = function() {
    // do we want to require for this? It's a FunctionExpression
};

foo(function() {
    // this is a FunctionExpression, too. 
});

(function() {
    // this is a FunctionExpression, too.
}());

// these?
var foo = () => {};
foo(() => {});

[yfr]

Ok. I see your point. Is there a way to make more precise decisions? I personally would like the first two to have jsDoc required.

Do you think it's worth building a plugin? Or is this just to special?

[nzakas]

We can be more specific, we just have to know what to look for.

I like the idea of a require-jsdoc rule as part of ESLint. Just need to figure out the correct options.

[grabbou]

@nzakas what about starting with all prototype methods and class methods in ES6? Once the feature is up & running, we can figure out other places where it should work. If that's something you'd like to see working, can submit the proposal.

[xjamundx]

I think any FunctionDeclaration at the root of a file would be what I'd personally want to see, but I can see how this depends drastically on the project (are you using a lot of prototypes or ES6 classes) and module system being used (that wouldn't work for AMD for example).

We may also talk to @nrsedat about his plugin to see if he has any ideas based on his plugin.
https://github.com/nrsedat/eslint-plugin-require-jsdoc

Some ideas for possible config options we could turn on or off:

• declarations (i.e. function a() {})
• es6Classes
• es6Methods
• vars
• methods (meaning { x: function() {} }
• expressions ( meaning var x = function() {} and even x.prototype.thing = function() {})

[nzakas]

@grabbou we need to stay with something that easily lends itself to extension later, that's the tricky part.

@xjamundx I think the naming is the big problem to solve here. Some of these are pretty ambiguous

[andreas-marschke]

Hi! I have a PR to run fail eslint on undocumented named functions it's here: #2980

If you'd like to have this issue resolved feel free to comment on the PR.

[sebastienbarre]

Thanks for creating this rule. Was wondering if I'm missing something here. Shouldn't it be triggered for FunctionExpression as well? This, for example, doesn't trigger any error, even though it has no doc block:

var promiseRejectError = function() {
  return Promise.reject(Error('boom'));
};

The source code seems to mention it, but FunctionExpression is not an accepted configuration option.

Thanks

[gyandeeps]

Yup we do not support FunctionExpression (ref docs).

[sebastienbarre]

@gyandeeps Thanks. Any particular rationale? I was wondering about the code in the rule:

        "FunctionExpression": function(node) {
            if (options.MethodDefinition) {
                checkClassMethodJsDoc(node);
            }
        },

[JustinLivi]

Are there any plans to support function expressions? It seems very useful when documenting modules. For example, right now there's no way to consider this a problem:

module.exports.foo = function foo() {
    return 'bar';
}

[vobu]

+1 on this

[platinumazure]

Please open a new issue if you want an enhancement to this rule. Thanks!

[vobu]

here it is: #5867