"requireParamDescription" when set to false, it should not flag parameters without trailing hyphens
See original GitHub issueWhat rule do you want to change?
I would like to change the a rule for “valid-jsdoc”, requireParamDescription
.
Does this change cause the rule to produce more or fewer warnings?
It should reduce warnings.
How will the change be implemented? (New option, new default behavior, etc.)?
The change is to ignore trailing hyphens at the beginning of the parameter description in a JSDoc comment.
This is the intended JSDoc behavior, as noted in this link:
http://usejsdoc.org/tags-param.html
Where JSDoc allows only the name and type for a @param
entry, like so:
/**
* @param {string} somebody
*/
function sayHello(somebody) {
alert('Hello ' + somebody);
}
Please provide some example code that this change will affect:
Using the following code:
/**
* Demo
* @param {number} a -
* @param {number} b
* @param {number} c --------------------------------------------------------
* @returns {number} Sum
*/
function hello(a, b, c){
return a + b + c;
}
hello(1, 2, 3);
Here in this JSDoc, the example shows parameter 1 is correct, parameter 2 is incorrect, parameter 3 is correct, and the return is correct. Reason why parameter 2 is incorrect, is because it does not have a trailing hyphen.
The new change should say the description without any trailing hyphens is valid, because there really isn’t any requirements for a description. A trailing hyphen is somehow weird, and does not fit the rule’s intended purpose of not requiring parameter descriptions, especially with the trailing hyphen.
What does the rule currently do for this code?
The current rule states that the parameter description must be required to at least insert or append a single trailing hyphen.
What will the rule do after it’s changed?
The new changed rule will allow an empty description to be a valid JSDoc.
Issue Analytics
- State:
- Created 5 years ago
- Comments:7 (3 by maintainers)
Top GitHub Comments
@platinumazure
Hi, thanks for the response. I wrote a wiki article in an obscure Microsoft repository for Visual Studio Code here:
https://github.com/Microsoft/vscode-eslint/wiki/Visual-Studio-Code:--Setting-up-ESLint-Rules-(Beginner’s-Introduction)
The only suggestion (split into 2 parts) that I have right now is, because setting up ESLint on many different editors all have their own quirks and methods of applying ESLint rules, there really isn’t a standardized method of specifying or applying ESLint rules to the way the user wanted.
The hard part is:
It would be nice for ESLint to come up with a standardized rules layout, much akin to C++ standard, ECMAScript standard, or something where it’s strictly enforcing a certain syntax format, so all editors must apply the same strict syntax when integrating ESLint into their workflows.
The easier part is:
The documentation should have an article of a general list of supported syntaxes for writing ESLint rules. Some editors support configuration files written in JSON for ESLint, so JSON syntaxes should be one of the many supported syntaxes on that article. There are some that are Batch files based, Bash/Shell scripts, .editorconfig based, or even INI files.
Again, it’s the breath of configuration syntaxes that are too broad for me to search for the right syntaxes suitable for the editor I’m using. That’s the issue right now for me. But maybe one of the contributors know more than me and knows how to address this issue going forward.
That’s all.
Thanks for taking the time to write a detailed response, @tommai78101. I’ll think on it and see what we can do.