Empty docblocks are added above functions on lint

[ay13]

When I run the linter at adds empty docblocks above every function that doesn't already have a docblock. I assume this is part of the auto fixing but this messes doc coverage reports by incorrectly reporting that a function is documented when it is not.

Is there a way to disable the behavior of auto adding empty doc blocks?

[brettz9]

ESLint unfortunately does not provide a means of selectively disabling rules for fixing; one apparently needs to specify a separate config for fixing (where the fixing config, in this case, would omit/disable the require-jsdoc rule).

@gajus and @golopot, what do you think of a disableFixer option that could be added to each rule to disable the fixer for any rule with a fixer? #336 already anticipates separate options for those rules that have multiple possible fixing strategies, so it might not be too big of a change.

It'd be nice if eslint offered an easier way, e.g., while loading a config, be able to disable specific rules within that config dynamically on the command line, but I received no feedback, at least on this comment on a related issue: eslint/eslint#11747 (comment) .

[gajus]

I am probably misunderstanding something. If the intention is to have jsdoc block for every function, then require-jsdoc should be enabled and it is expected to "fix" codebase. If there is no such intention, then require-jsdoc should not be enabled and it is not anticipated to "fix" codebase.

To me this particular issue sounds like it is more about strictness of require-jsdoc. I would argue that a fixer that simply creates an empty jsdoc block doesn't add much value and just creates noise.

[brettz9]

I am seeing the issue as the fact that projects will probably not want to go to the trouble of dynamically generating their config files (so that they could, for example, enable require-jsdoc in one non-fixing config to get linting warnings where jsdoc blocks were missing, but have the rule disabled in a separate --fix config so as not to get the comment block added), and would rather just use a single config file for both identifying linting issues and fixing them.

A related problem as I see it is that projects may differ in what they consider to be a reasonable fix. I would personally find the automatic addition of comment blocks to be useful, especially if starting with a project which had many items to be commented--it would also serve as a visual reminder of the need to document and an invitation to do so more quickly.

As discussed in #47, there may be other fixers which might be desired by some projects, but not others; for example, stripping bad param names might be seen as useful for removing stale param info by some projects, or a risk for removing mere bad spellings by another.

[carlrannaberg]

This rule being as fixable is not very useful for us. Especially if it tries to fix it even when it is reported as warning.

Rule configuration:

'jsdoc/require-jsdoc': ['warn', {
	publicOnly: true,
	require: {
		ArrowFunctionExpression: true,
		ClassDeclaration: true,
		ClassExpression: true,
		FunctionDeclaration: true,
		FunctionExpression: true,
		MethodDefinition: true
	}
}]

This is what happens in our codebase when this rule is turned on:
Before:

module.exports = {
    set(key, value, ttl, callback) {
        // code
    }
};

After:

module.exports = {
    set/**
        *
        *//**
           *
           *//**
              *
              *//**
                 *
                 *//**
 *
 */
    (key, value, ttl, callback) {
        // code
    }
};

Having this kind of result unfortunately makes this rule pretty much useless for us. It would be great if the autofix could be turned off for this rule as I only want to see warnings about functions without JSDoc comments. Any idea how to accomplish that?

Currently the most viable option for just reporting the warnings without fixing is to use the deprecated ESLint rule require-jsdoc. Unfortunately it lacks some the configuration options that the jsdoc/require-jsdoc rule has.

[brettz9]

@carlrannaberg : I think this might related to problems in the stringifier of comment-parser (or a limitation of what the stringifier could represent). I'm afraid I'm a bit tied up to investigate this. As a workaround, I can only suggest having a separate config, one which is for checking only (and has the rule enabled) and one for fixing (which has it disabled). But I'd suggest filing that as a separate issue as this particular issue is for an enhancement to disable fixing, but your case looks like a problem with the fixing itself.

[brettz9]

Btw, @carlrannaberg, not sure if the issue was fixed by #524, but I am no longer seeing the recursive issue mentioned in #372 (comment)

[brettz9]

@gajus , @golopot : I really hope we can at least keep the addition of empty jsdoc blocks as an option, as I find them very useful not only for saving a little time in data input but also for being a visual reminder of the need to document (and if one doesn't want empty descriptions to get past linting, one can use match-description to report on this). And getting documentation added is also useful because with rules being atomic, rules like require-returns, etc. won't report if the jsdoc block is missing, so allowing the auto-addition of doc blocks exposes a more complete list of required documentation to-dos.

However, as another request has been made to disable such a fixer (#594 ) I can make a PR to avoid the fixer, adding a enableFixer boolean (such as we have with the require-param and check-param-names rules) if that is all right. Let me know if you want a somewhat breaking change to make the option (to enable the fixer) off by default.