Proposal: JSDoc only on exported nodes

What rule do you want to change?

require-jsdoc - link

Support making a rule so that the ESLinters for JSDocs are only applied on items which are going to leave the current source file ( and thus would be visible outside of the current scope. )

Does this change cause the rule to produce more or fewer warnings?

It would add an option to produce fewer warnings.

How will the change be implemented? (New option, new default behavior, etc.)?

There could be a scope attribute to require-jsdoc which allows you to define whether to apply the rules to all nodes. Or to only ones which will be available outside of it’s file.

{
    "require-jsdoc": ["error", {
       "scope": "all" || "exported",
        "require": {
            "FunctionDeclaration": true,
            "MethodDefinition": false,
            "ClassDeclaration": false,
            "ArrowFunctionExpression": false
        }
    }]
}

Please provide some example code that this change will affect:

for Modern: import/export

export class MyThing {}
export function simpleFunction(one, two) {}

For the require style, something like this

module.exports = class Runner extends EventEmitter {}

module.exports.jestChildProcessWithArgs = (workspace: ProjectWorkspace, args: Array<string>): ChildProcess => {}

So for some example code:

var foo = (test) => {
    return test + 10;
}

/**
 * It returns 10
 */
export class Test{
    /**
    * returns the date
    */
    getDate(){}
}

What does the rule currently do for this code?

At the moment all JSDoc checks are applied wholesale throughout your source code. Meaning even internal functions, or test helper functions require comprehensive comments. So this would raise errors for foo but not test.

What will the rule do after it’s changed?

With the scope as exported then the code above would not produce any errors.

[nzakas]

Okay, I’ll champion - I think this is a nice addition.

@orta feel free to submit a PR.

[nzakas]

@byk please add your 👍 to the issue description so we can keep track.

For “scope” we could make it “exportedOnly” to change it into a Boolean option. We probably don’t need a string unless we think there might be a third option.