Docs: Confused by options for require-hyphen-before-param-description

[thernstig]

Caveat: I deleted the entire template due to this being a doc issue.

https://github.com/gajus/eslint-plugin-jsdoc/#options says:

eslint-plugin-jsdoc options, if present, are in the form of an object supplied as the second argument in an array after the error level.

require-hyphen-before-param-description (https://github.com/gajus/eslint-plugin-jsdoc/blob/master/.README/rules/require-hyphen-before-param-description.md) says:

Options
This rule takes one optional string argument and an optional options object.

https://github.com/gajus/eslint-plugin-jsdoc/#require-hyphen-before-param-description also has examples that say:

Options: ["always",{"tags":{"*":"never"}}]

This seems to contradict eachother. The first links says it should be an object. The other two indicates it is an array.

[thernstig]

For reference these are the things I have tried:

"jsdoc/require-hyphen-before-param-description": [
  "always",
  { "tags": { "*": "never" } }
],
// gives "Severity should be one of the following: 0 = off, 1 = warn, 2 = error (you passed '"always"')."

"jsdoc/require-hyphen-before-param-description": [
  "warn",
  ["always", { "tags": { "*": "never" } }]
],
// gives "Value ["always",{"tags":{"*":"never"}}] should be string."

"jsdoc/require-hyphen-before-param-description": [
  "warn",
  "always"
],
// gives "Value {"avoidExampleOnConstructors":true,"exemptedBy":["type"],"checkConstructors":true,"checkGetters":false,"checkSetters":false,"exemptNoArguments":false} should NOT have additional properties."

[thernstig]

I can also add that the table looks weird. The last "Options" seems to be half-complete. This seems to be a copy&paste from other places that also has this half-complete example. In addition, other tables with "Options" are always property names.

Context	everywhere
Tags	param and optionally other tags within tags
Aliases	arg, argument; potentially prop or other aliases
Recommended	false
Options	(a string matching `"always"

I find it confusing that all examples on https://github.com/gajus/eslint-plugin-jsdoc/#require-hyphen-before-param-description add // Options: [{"exemptTagContexts":[{"tag":"typedef","types":true}]}] as an array when the options is always an object in ESLint.

[brettz9]

Caveat: I deleted the entire template due to this being a doc issue.

Thanks. For the future, I've created a new template just for doc bugs.

https://github.com/gajus/eslint-plugin-jsdoc/#options says:

eslint-plugin-jsdoc options, if present, are in the form of an object supplied as the second argument in an array after the error level.

require-hyphen-before-param-description (https://github.com/gajus/eslint-plugin-jsdoc/blob/master/.README/rules/require-hyphen-before-param-description.md) says:

Options
This rule takes one optional string argument and an optional options object.

https://github.com/gajus/eslint-plugin-jsdoc/#require-hyphen-before-param-description also has examples that say:

Options: ["always",{"tags":{"*":"never"}}]

This seems to contradict eachother. The first links says it should be an object. The other two indicates it is an array.

Yes, thank you. I've amended the docs to indicate that this is only generally the case. Some rules, following the eslint practice, do indeed have a string (currently, just "always" or "never") as the first option.

For reference these are the things I have tried:

"jsdoc/require-hyphen-before-param-description": [
  "warn",
  "always"
],
// gives "Value {"avoidExampleOnConstructors":true,"exemptedBy":["type"],"checkConstructors":true,"checkGetters":false,"checkSetters":false,"exemptNoArguments":false} should NOT have additional properties."

While your other expected warnings are expected (which hopefully the docs now clarify), this last result does not seem it should be happening. You might want to check this latter example again, because I would expect this would work. If not, you can file a regular bug report about it.

I can also add that the table looks weird. The last "Options" seems to be half-complete. This seems to be a copy&paste from other places that also has this half-complete example. In addition, other tables with "Options" are always property names.

Context everywhere
Tags param and optionally other tags within tags
Aliases arg, argument; potentially prop or other aliases
Recommended false
Options (a string matching `"always"

Thank you. This is now fixed. Was a Markdown escaping issue. As far as property names, we don't want property names here because this is a case where the first option is indeed a string, so there is no property to list.

I find it confusing that all examples on https://github.com/gajus/eslint-plugin-jsdoc/#require-hyphen-before-param-description add // Options: [{"exemptTagContexts":[{"tag":"typedef","types":true}]}] as an array when the options is always an object in ESLint.

While following the approach of ESLint testing tools is not necessarily user friendly, and we therefore might consider stripping off the [ and ], leading to something like Options: "always",{"tags":{"*":"never"}}, I wonder whether the array syntax better clarifies and reminds people to use an array when specifying options (since needed for adding the likes of ['warn', 'always']). Maybe we could change it to the following to more clearly suggest the structure:

Options: ["error"|"warn", "always", {"tags":{"*":"never"}}]

I'm marking the issue as fixed since the problematic items are now handled, but feel free to comment further on this latter question.

[thernstig]

First of, thank you for answering so elegantly. Very much appreciated, it all makes sense now.

https://eslint.org/docs/user-guide/configuring/rules#configuring-rules says:

If a rule has additional options, you can specify them using array literal syntax, such as:

So it calls the entire array "Options" in this case.

What threw me of in the documentation here https://github.com/gajus/eslint-plugin-jsdoc#options was:

eslint-plugin-jsdoc options, if present, are generally in the form of an object

and

// The options vary by rule, but are added to an options object:

ESLint makes it sound like even "off/error/warn" are part of the options array. So I think your last example might help here. But also as you say, re-write the options chapter slightly.

You are right, this works. I made a mistake before:

"jsdoc/require-hyphen-before-param-description": [
  "warn",
  "always"
],

[brettz9]

it all makes sense now.

Glad to hear it.

What threw me of in the documentation here https://github.com/gajus/eslint-plugin-jsdoc#options was:

// The options vary by rule, but are added to an options object:

Ah, good catch there too. I've amended it to say:

// The options vary by rule, but are generally added to an options
// object as follows:

[brettz9]

But also as you say, re-write the options chapter slightly.

I guess you mean eslint's docs on configuration. We are independent from them, so you'd have to report a desire for changes at https://github.com/eslint/eslint/issues (or communicate with their developers by their Discord chat).

[brettz9]

ESLint makes it sound like even "off/error/warn" are part of the options array. So I think your last example might help here.

@gajus, are you ok with my changing the README output from producing the likes of:

Options: ["always", {"tags":{"*":"never"}}]

to:

Options: ["error"|"warn", "always", {"tags":{"*":"never"}}]

?

[thernstig]

I guess you mean eslint's docs on configuration. We are independent from them, so you'd have to report a desire for changes at https://github.com/eslint/eslint/issues (or communicate with their developers by their Discord chat).

I meant https://github.com/gajus/eslint-plugin-jsdoc#options

Shouldn't this line also get an update:

eslint-plugin-jsdoc options, if present, are generally in the form of an object supplied as the second argument in an array after the error level (any exceptions to this format are explained within that rule's docs).

That one makes it sound like the options is only the object, when in fact it is more. Even including "error"|warn". As https://eslint.org/docs/user-guide/configuring/rules#configuring-rules says:

If a rule has additional options

The term additional makes it sound like everything for a rule is considered "options", including "error"|"warn".