Why doesn't jsdoc/check-param-names check for property defaults?

[krutoo]

Hi, rule jsdoc/check-param-names throws an error with destruture prop and

Here an example of code:

it causes errors iin terminal:

/home/petrov_dm/Projects/sima/ui-nucleons/src/components/rating/index.jsx
  55:0  error  @param "props.starSizes.regular" does not exist on props            jsdoc/check-param-names
  56:0  error  @param "props.starSizes.big" does not exist on props                jsdoc/check-param-names
  60:0  error  @param "props.customClasses.rating" does not exist on props         jsdoc/check-param-names
  61:0  error  @param "props.customClasses.hoveredRating" does not exist on props  jsdoc/check-param-names
  62:0  error  @param "props.customClasses.star" does not exist on props           jsdoc/check-param-names
  63:0  error  @param "props.customClasses.emptyStar" does not exist on props      jsdoc/check-param-names
  64:0  error  @param "props.customClasses.halfStar" does not exist on props       jsdoc/check-param-names
  65:0  error  @param "props.customClasses.fullStar" does not exist on props       jsdoc/check-param-

how can i allow to specify fields which are not specified explicitly during destructuring?

[brettz9]

Can you please paste a minimal code example instead of a screenshot? Thanks...

[krutoo]

@brettz9

Here an js code:

/**
 * Returns a number.
 * @param {Object} props Props.
 * @param {Object} props.prop Prop.
 * @param {string} props.prop.a String.
 * @param {string} props.prop.b String.
 * @param {string} props.prop.c String.
 * @return {number} A number.
 */
export function testFn1 ({ prop = { a: 1, b: 2, c: 3 } }) {
  return [prop.a, prop.b, prop.c].map(Number).reduce((i, j) => i + j) + 123;
}

There is no destructure of prop and maybe it is not a bug according to description of rule,

but how can i allow to specify fields which are not specified explicitly during destructuring

[brettz9]

Yeah, we don't currently allow treating a default as something to examine for its properties. For that I would have a typedef, such as:

/**
 * @typedef {Object} PropObj
 * @property {string} a String.
 * @property {string} b String.
 * @property {string} c String.
 */

/**
 * Returns a number.
 * @param {Object} props Props.
 * @param {PropObj} props.prop Prop.
 * @return {number} A number.
 */

Otherwise, you'd have to either set checkDestructured: false or just disable the rule (and rely on require-pram to check in the other direction). As long as we're checking that destructuring are present, we have to be able to find them.

Admittedly, in your particular type of case, it is possible we could add code to look through the default object properties (which is different from destructuring) and allow those, so we can leave this issue as a feature request if you like.

[krutoo]

Thank you @brettz9

[brettz9]

I think now there actually a couple action items out of this to which we can add as options:

1. useDefaultObjectProperties - for loosening check-param-names (no need for docs if found on default object instead of being destructured) and tightening require-param (insist on documentation if a property is found in a default object). I've submitted require-param and check-param-names: useDefaultObjectProperties option #678 to address this.
2. disableExtraPropertyReporting - for extra property docs with check-param-names. With this option, we could still keep the other destructuring checks like ensuring params have roots but without the errors you reported (except where another item at the same level has been destructured, I think as I think we should perhaps always report this as there is less purpose to document if the function doesn't even use it). I've submitted Disable extra property reporting #679 to address this.