checkDestructured property to disable destructured checks

[brettz9]

Currently builds on #531

Allows disabling of destructured checks (by setting checkDestructured to false).

Fixes #530.

[golopot]

This message is confusing, what is root0?

[brettz9]

This is part of the feature added in #498 --that when a destructured parameter is also missing its root declaration, that by default, the word "root" will be used followed by a 0-based auto-incrementing number for each subsequent root (one can avoid the numeric additions with specific config, or add additional items to an options array so that until all the items in the array are exhausted, it will cycle through the names, e.g., ["root", "cfg", "config"] will add @param root then @param cfg, then @config0, with the last item auto-incrementing). You could see our discussion about it in the PR for more background.

[brettz9]

Though I think it makes sense to use root0 in the fixes, subject to user configuration (disablable by setting enableRootFixer to false), we could give a message like "Missing JSDoc @param destructuring root object declaration". Does that sound better? And I'd be personally ok having enableRootFixer default to false, but sometimes I think it is good when the defaults are--within reason and not genuinely harmful--a little on the aggressive side since it informs users of the features they might not learn about otherwise, and if they don't want it, they can come looking for how to disable.

[golopot]

Missing JSDoc @param declaration for destructured parameter {bar}.

[brettz9]

That could potentially become quite long though, no? e.g., {bar, baz, foo: {def: {ghi}}, many, others}

[brettz9]

I guess we could just slice it to a certain maximum length, adding ellipses as needed, and the curly bracket always at the end.

[brettz9]

How should we differentiate in this test case though?

      code: `
          /**
           *
           */
          function quux ({foo}) {

          }
      `,
      errors: [
        {
          message: 'Missing JSDoc @param "root0" declaration.',
        },
        {
          message: 'Missing JSDoc @param "root0.foo" declaration.',
        },
      ],
      output: `
          /**
           * @param root0
           * @param root0.foo
           */
          function quux ({foo}) {

          }
      `,

Report Missing JSDoc @param "{foo}" declaration twice?

[brettz9]

We don't want to report just once because the root object may or may not already be defined, and if not defined, there should continue to be a separate message and fix.

[brettz9]

Btw, if it's ok, can we discuss this as a separate issue for fixing reporting messages? This discussion, though valid, is concerning a preexisting behavior (we refer to root0 in other messages, not just in this PR). It would be nice to get this merged so the disabling functionality is available sooner.

[brettz9]

As far as the solution, I guess I can just change it to report:

Missing JSDoc @param "{foo}" declaration
Missing JSDoc @param "foo" in "{foo}" declaration

[gajus]

🎉 This PR is included in version 25.4.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀