publicOnly ignored when inside public functions that are missing jsdoc

[FTWinston]

When the publicOnly option is specified, the rule seems to be triggered for local functions within public members, if the public member itself lacks jsdoc. This is similar to #654, but with an extra caveat.

Expected behavior

Local (nested) functions should not trigger a linter failure if not documented, regardless of whether the enclosing public function is missing required jsdoc.

Actual behavior

Local (nested) functions trigger a linter failure if not documented, but only when the enclosing public function is missing required jsdoc.

ESLint Config

module.exports = {
	plugins: ['jsdoc'],
	rules: {
		'jsdoc/require-jsdoc': [
			'error',
			{
				publicOnly: true,
				require: {
					ClassDeclaration: true,
					ClassExpression: true,
					ArrowFunctionExpression: true,
					FunctionDeclaration: true,
					FunctionExpression: true,
					MethodDefinition: true,
				},
			},
		],
	},
};

ESLint sample

The inner function here triggers the rule:

export function outer() {
    function inner() {
        console.log('foo');
    }

    inner();
}

But the inner function here does not:

/**
 *
 */
export function outer() {
    function inner() {
        console.log('foo');
    }

    inner();
}

Environment

• Node version: 16.13.0
• ESLint version: 7.32.0
• eslint-plugin-jsdoc version: 37.2.0

[FTWinston]

This is a bit of an edge case, and only really relevant when applying eslint-plugin-jsdoc to code that didn't already use it.

[brettz9]

The applying of eslint-plugin-jsdoc to code that didn't already use it is handled within the jsdoc/require-jsdoc rule specifically.

Since the other example should trigger the rule since the main export is missing jsdoc, it appears you mean that what is happening is that we are misreporting the line number for jsdoc/require-jsdoc as coming from the inner function when it should be reporting the outer public one. Is that correct?

[brettz9]

Ah testing locally, it appears instead that we are reporting both the inner and outer in such a case when we should only be reporting one...

[FTWinston]

Yes, that's what I'd meant. Sorry for the confusion!

Outer correctly reports an error, but inner also reports an error, incorrectly.

It's only really an issue when the fixer is enabled, as it creates an extra comment block.

[brettz9]

This is somewhat of a hackish solution, but will hopefully do the trick.

[gajus]

🎉 This issue has been resolved in version 37.2.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[FTWinston]

Wow that was fast, thanks!

That's fixed the problem with nested function declarations, but an equivalent problem still occurs with nested arrow functions.

i.e. with inner here:

export const outer = () => {
    const inner = () => {
        console.log('foo');
    };

    inner();
};

and here:

export function outer() {
    const inner = () => {
        console.log('foo');
    };

    inner();
};

but not here:

export const outer = () => {
    function inner() {
        console.log('foo');
    }

    inner();
};

My apologies for not mentioning arrow functions previously. Would you like me to raise a separate ticket?

[gajus]

🎉 This issue has been resolved in version 37.2.2 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[FTWinston]

Superb, thanks!