Missing JSDoc param in .vue file

[Holiden]

Hello!

Expected behavior

It is expected that the plugin will not display a missing parameter error as they are already defined.

Actual behavior

I am getting an error about missing parameters. However, my JSDoc are filled in correctly. This is .vue file.

If use the suggested autofix, then the parameters are inserted before existing JSDoc declaration

When editing a file anywhere, errors disappear. Not always, but sometimes it works

ESLint Config

module.exports = {
  plugins: ['jsdoc', 'vue'],
  parser: 'vue-eslint-parser',
  parserOptions: {
    parser: '@babel/eslint-parser',
    sourceType: 'module',
  },
  rules: {
    'jsdoc/check-alignment': 'error',
    'jsdoc/check-param-names': ['error', { checkRestProperty: true }],
    'jsdoc/check-property-names': 'error',
    'jsdoc/check-tag-names': 'error',
    'jsdoc/check-types': 'error',
    'jsdoc/newline-after-description': 'error',
    'jsdoc/no-bad-blocks': 'error',
    'jsdoc/no-undefined-types': 'error',
    'jsdoc/require-description': 'error',
    'jsdoc/require-description-complete-sentence': 'error',
    'jsdoc/require-hyphen-before-param-description': 'error',
    'jsdoc/require-param': ['error', { checkRestProperty: true, enableFixer: false }],
    'jsdoc/require-param-description': 'error',
    'jsdoc/require-param-name': 'error',
    'jsdoc/require-param-type': 'error',
    'jsdoc/require-property': 'error',
    'jsdoc/require-property-description': 'error',
    'jsdoc/require-property-name': 'error',
    'jsdoc/require-property-type': 'error',
    'jsdoc/require-returns': 'error',
    'jsdoc/require-returns-check': 'error',
    'jsdoc/require-returns-description': 'error',
    'jsdoc/require-returns-type': 'error',
    'jsdoc/require-throws': 'error',
    'jsdoc/require-yields': 'error',
    'jsdoc/require-yields-check': 'error',
    'jsdoc/valid-types': 'error',
  }
}

Environment

• Node version: v14.16.1
• ESLint version: v7.24.0
• eslint-plugin-jsdoc version: v32.3.3
• IDE: Php Storm 2021.1.1

[brettz9]

If you can create a minimal test case repo, there is a greater chance we can debug this. I don't know it if may relate to your Webpack or Rollup routine.

[Holiden]

If you can create a minimal test case repo, there is a greater chance we can debug this. I don't know it if may relate to your Webpack or Rollup routine.

Yes of course. Here it is.
src/App.vue - all the same.

[brettz9]

Using the command line, $(npm bin)/eslint --ext=vue ., I only get one unrelated error, "Missing an explicit type attribute for button vue/html-button-has-type".

When viewing within Atom, I get an error about no Babel config file being detected, but when I add babelOptions like thus (and I wasn't able to use ~/ for some reason):

  parserOptions: {
    babelOptions: {
      cwd: '/Users/brett',
      configFile: './forJSDoc/babel.config.js'
    },
    parser: '@babel/eslint-parser',
    sourceType: 'module',
  },

...I also just get the same error as on the command line.

Perhaps this is an issue specific to your IDE.

[Holiden]

Perhaps this is an issue specific to your IDE.

I tried opening it in VSCode and got the same errors

[Holiden]

I will clarify what it is in the files .vue. In files .js everything is correct.

[brettz9]

Do you have Atom available to test? I'm not sure why it would be working there... What was the original IDE you were using?

[Holiden]

Do you have Atom available to test? I'm not sure why it would be working there... What was the original IDE you were using?

• IDE: Php Storm 2021.1.1

I do not have Atom, but i can set it for test.

[brettz9]

I'm afraid I'm rather tied up in other projects to really explore this too deeply atm myself.

Hopefully someone can go to /node_modules/eslint-plugin-jsdoc/dist/rules/requireParam.js and add logging (or throwing errors as need be for the IDE to pick it up) around the Missing JSDoc to find out where things are going wrong.

Or perhaps it can be solved by adjusting the IDE's settings, e.g., ala babel/babel-eslint#769 (comment) , in case your @vue/cli-plugin-babel/preset is required but is not getting discovered.

Hope that leads to some avenues of exploration, as I'm not really too sure at this point.

[gcunsolo]

Hi all,

I'm having the very same issue when working on a Windows 10 OS.

Please note that I got no problem at all when using MAC OS.

Here's a sample of a file I'm trying to lint:

/**
     * @description My beautiful description
     * @param {string} param - This is an awesome param indeed
     * @return {boolean} true if not false
     */
    myBeautifulMethod(param) { ... }

Here's the output of my lint job:

   97:5  error  Missing JSDoc @description declaration        jsdoc/require-description
   97:5  error  Missing JSDoc @param "param" declaration     jsdoc/require-param
   97:5  error  Missing JSDoc @return declaration             jsdoc/require-returns

It's like the plugin found a JSDoc block, but was totally unable to analyze its content.

Just like @Holiden, If I try an autofix I got this result:

> 59 |     * @param param
     |       ^
  60 | /**
  61 |      * @description My beautiful description
  62 |      * @param {string} param - This is an awesome param indeed

From where I stand, it looks like a bad detection of end-of-line after the /**

Edit:
Browsing your issues, the only problem that looks vaguely related may be #431

[gcunsolo]

When editing a file anywhere, errors disappear. Not always, but sometimes it works

Again, I got the very same behaviour.

@Holiden Can you please confirm my lead about Windows OS? Thanks in advance

[brettz9]

@gcunsolo : If you can use plugins with jsdoc and add the rules individually (instead of using extends with plugins:jsdoc/recommended), can you try removing one half of the rules and through the process of elimination, identify which single rule may be sufficient to trigger the problem (is it require-param` alone?)

Then, if you could reduce your code down to see whether that comment block alone in a file is sufficient to trigger the error...

And if you would also try upgrading to the latest eslint-plugin-jsdoc, since the reported version is several versions earlier now, and it is possible there was some fix.

[gcunsolo]

Thank you @brettz9

I'm currently using 33.1.1, I'll give 34.0.2 a shot and get back to you with more information, as you asked!

(...and hey! Good job! We all get here to complain when there's something wrong... we never take the time to thank you all for your work!!)

[Holiden]

@Holiden Не могли бы вы подтвердить мое мнение об ОС Windows? заранее спасибо

All right. This is the problem I have on OS Windows 10.

[brettz9]

While this doesn't look necessarily Windows specific, you might perhaps take a look at this JSDoc stripping issue referenced at https://github.com/jsdoc2md/jsdoc-to-markdown/wiki/How-to-document-TypeScript#tips--tricks

[gcunsolo]

Hi @brettz9
Here's the result of my latest tests (v 34.8.2)

The "broken" rules are require-description, require-param and require-returns.
Executing lint with these rule gives unexpected results (see previous comment)

I confirm that require-param alone triggers the files corruption problem on autofix.
(expected, since it's the only rule having autofix capabilities)

For your information, I executed your unit tests and I got the following output:

Rule, `require-param`, missing line numbers in errors: 24                                                                                                                                                                                                                      
  [▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬]                                                                                                                                                                                                                                       
  1943 passing (6s)                                                                                                                                                                                                                                                            

Tests are passing, and yet that log concerning require-param makes me curious :)

eslint-plugin-jsdoc/test/rules/index.js

Lines 48 to 55 in 9fb6b36

	// Make an exception for now for `require-param` as it helps to find the
	// many lines were it is missing to know which tests to check without
	// adding false (or failing) expectations now
	if (ruleName === 'require-param') {
	// eslint-disable-next-line no-console -- CLI
	console.log(
	`Rule, \`${ruleName}\`, missing line numbers in errors: ${count}`,
	);

As I said before, it looks like only when using Windows the plugin is able to identify a JSDoc block but totally unable to parse its content.

As an additional note, I tried to play with your iterateJsdoc to replace the /n at lines 139 and 159 with no luck

eslint-plugin-jsdoc/src/iterateJsdoc.js

Lines 114 to 162 in 6b6d908

	utils.getTagDescription = (tg) => {
	const descriptions = [];
	tg.source.some(({
	tokens: {end, postDelimiter, tag, postTag, name, type, description},
	}) => {
	const desc = (
	tag && postTag ||
	!tag && !name && !type && postDelimiter || ''
	// Remove space
	).slice(1) +
	(description || '');
	if (end) {
	if (desc) {
	descriptions.push(desc);
	}
	return true;
	}
	descriptions.push(desc);
	return false;
	});
	return descriptions.join('\n');
	};
	utils.getDescription = () => {
	const descriptions = [];
	let lastDescriptionLine;
	jsdoc.source.some(({tokens: {description, tag, end}}, idx) => {
	if (idx && (tag || end)) {
	lastDescriptionLine = idx - 1;
	return true;
	}
	if (idx || description) {
	descriptions.push(description);
	}
	return false;
	});
	return {
	description: descriptions.join('\n'),
	lastDescriptionLine,
	};
	};

[brettz9]

Hi @gcunsolo ,

Here's the result of my latest tests (v 34.8.2)

The "broken" rules are require-description, require-param and require-returns.
Executing lint with these rule gives unexpected results (see previous comment)

I confirm that require-param alone triggers the files corruption problem on autofix.
(expected, since it's the only rule having autofix capabilities)

Thanks for this info.

For your information, I executed your unit tests and I got the following output:

Rule, `require-param`, missing line numbers in errors: 24                                                                                                                                                                                                                      
  [▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬]                                                                                                                                                                                                                                       
  1943 passing (6s)                                                                                                                                                                                                                                                            

Tests are passing, and yet that log concerning require-param makes me curious :)

Yeah, I hard-coded this warning. We need to fix require-param to report more accurate line numbers. I didn't have time to complete my work on that review, so I put that warning to avoid adding bad test expectations which would satisfy the tests and avoid the need for that warning, but which would make it harder to find the offending line numbers when I or someone got around to fixing them. In short, this shouldn't be connected to our current problems with this issue.

As I said before, it looks like only when using Windows the plugin is able to identify a JSDoc block but totally unable to parse its content.

As an additional note, I tried to play with your iterateJsdoc to replace the /n at lines 139 and 159 with no luck

eslint-plugin-jsdoc/src/iterateJsdoc.js

Lines 114 to 162 in 6b6d908

	utils.getTagDescription = (tg) => {
	const descriptions = [];
	tg.source.some(({
	tokens: {end, postDelimiter, tag, postTag, name, type, description},
	}) => {
	const desc = (
	tag && postTag ||
	!tag && !name && !type && postDelimiter || ''
	// Remove space
	).slice(1) +
	(description || '');
	if (end) {
	if (desc) {
	descriptions.push(desc);
	}
	return true;
	}
	descriptions.push(desc);
	return false;
	});
	return descriptions.join('\n');
	};
	utils.getDescription = () => {
	const descriptions = [];
	let lastDescriptionLine;
	jsdoc.source.some(({tokens: {description, tag, end}}, idx) => {
	if (idx && (tag || end)) {
	lastDescriptionLine = idx - 1;
	return true;
	}
	if (idx || description) {
	descriptions.push(description);
	}
	return false;
	});
	return {
	description: descriptions.join('\n'),
	lastDescriptionLine,
	};
	};

Would need to take a closer look, but I would suspect Windows issues might be related to the recently discovered issue highlighted at #745 (comment) where the comment parser is dropping carriage returns. (I since reported the issue to syavorsky/comment-parser#129 and am now awaiting a reply).

[RonnyTite]

Hi @brettz9 ,

the issue is still happening even with syavorsky/comment-parser#129 closed.

So i have made a fork to reproduce this issue on my Windows. Basically i think its all related to line endings, windows files being CRLF .

fork can be found here : https://github.com/solven-eu/eslint-plugin-jsdoc/tree/reproduce_jsdoc_lint_error

here a litlle details , i've done to reproduce it:

• change the .editorconfig end_of_line property to crlf
• add a folder named 'errorToReport` that contains my tested files ( 1 .vue appToReport.vue and 1 .js toReport.js )
• add a new command in the package.json lintReport to lint fix only the .vue file ( because cannot reproduce on .js file)
• Install some plugin and made some changes on .eslintrc.json, to be compatible with .vue files

AND had to rename the name of the project to eslint-plugin-jsdoc-fork to be able to install eslint-plugin-jsdoc.. inside the project 😅

To reproduce , just launch the command lintReport and take a look at appToReport.vue

BEFORE

AFTER

and here the logs

   9:5  error  Unexpected comment inline with code     no-inline-comments
   9:5  error  Missing JSDoc @description declaration  jsdoc/require-description
  12:0  error  Missing JSDoc @param "arg" description  jsdoc/require-param-description

Hopes this can help

[brettz9]

Am a bit preoccupied these days; hopefully can take a look within a couple weeks time. Thanks!

[blacelle]

Hello,

The root-cause seems not in this library, as the SourceCode object holds a token lacking \n characters. For given PR, over a \r\n file under MacOS, the SourceCode object holds a token like:

  {
    type: 'Block',
    value: '*\r     * @description TESTSTETSTST\r     * @param {string} arg - lorem\r     * @return {string} - someDescription\r     ',
    start: 102,
    end: 223,
    loc: SourceLocation {
      start: [Object],
      end: [Object],
      filename: undefined,
      identifierName: undefined
    },
    range: [ 102, 227 ]
  },

while the SourceCode text (with \r and \n escaped) is:

<template>CRLF <div>HELLO WORLD</div>CRLF</template>CRLFCRLF<script>CRLFCRLFexport default {CRLF computed: {CRLF /**CRLF * @description TESTSTETSTSTCRLF * @param {string} arg - loremCRLF * @return {string} - someDescriptionCRLF */CRLF isForTestingLint (arg) {CRLF return arg;CRLF },CRLF },CRLF};CRLF</script>CRLF

-> The token holds \r without their \n sibling.

---

Over a \n files, the token is:

{
   type: 'Block',
   value: '*\n' +
     '     * @description TESTSTETSTST\n' +
     '     * @param {string} arg - lorem\n' +
     '     * @return {string} - someDescription\n' +
     '     ',
   start: 94,
   end: 215,
   loc: SourceLocation {
     start: [Object],
     end: [Object],
     filename: undefined,
     identifierName: undefined
   },
   range: [ 94, 215 ]
 },

Is SourceLocation a babel object, or from another library? (If ESLint, all this may be related with https://github.com/vuejs/vue-eslint-parser)

[brettz9]

ESLint apparently consumes these (per https://eslint.org/docs/developer-guide/working-with-custom-parsers#all-nodes ), but it looks like it would come from a parser.

[brettz9]

I've confirmed that this is a bug, but a bug apparently with vue-eslint-parser. I've filed vuejs/vue-eslint-parser#145 in the hopes they can handle it. Will close for now, as should be resolved once they fix this, though feel free to comment further upon definitive status updates there (e.g., if they may fix the issue and there are no longer problems or there are still problems). Thanks for the details, all, which helped better identify the source of the problem.

[brettz9]

Just reporting back that as per vuejs/vue-eslint-parser#145 , this issue should now be fixed, and that fix was included in version 8.3.0 of vue-eslint-parser.

Please confirm if it is working for you all. Thanks!