Eslint-plugin-jsdoc: Option to configure `require-param` to work identical to pre - v25

[michaelfarrell76]

To start off, I've really loved this plugin and especially the require-param rule. This has been great for enforcing consistency of docs on our team!

Our codebase is entirely typescript so we set 'jsdoc/require-param-type': 0, but leave on jsdoc/require-param since it will enforce that each function param has an associated comment which is HUGE.

The v25 major upgrade however caused some problems since every object param we had was automatically expanded to have the opts.arg1, opts.arg2 docs.

We practically never want this expansion to happen because all of these object params have an associated typescript type, and we use tslint completed-docs to enforce each param in our typescript types has a comment.

My Ask:

Is there a way that we can configured require-param to never do the automatic expansion of object params? I read the changelog and read the updated docs but I could not for the life of me figure out how to configure the eslint rules so that it never expanded, but still auto fixed to add a jsdoc for the arugment if it was missing. The old setup was so perfect and I :pray: that there's a way to configure this to keep fix on but to not warn or fix this object expansion

Bonus Points:

Also trying to move off of tslint and finding a full replacement for the completed-docs rule is really hard. We like to write out types like the following:

/**
 * A container definition
 */
export type Container = {
  /** Constants */
  constants?: ObjByString;
  /** Enumerated values, where the values are CONSTANT_CASE by default */
  enums?: { [key in string]: TypescriptEnum };
  /** Helper functions for that container */
  helpers?: { [key in string]: AnyFunction };
};

And the completed-docs rule can enforce that each of the type params (i.e. constants, enums, helpers has an inline jsdoc). I could see this being outside the scope of this pacakge, but would be incredible if that capability was done here in eslint and not tslint!

[brettz9]

I went for just the bonus points for now. :-)

While you could already use contexts to require documenting of the TSTypeAliasDeclaration context, this was only producing the full, indented, multi-line jsdoc blocks. I've now changed contexts (part of release 25.1.0) to also optionally accept objects whose context property would contain the context string and inlineCommentBlock is an optional boolean which allows for inline comments. (This object approach should also have the advantage that we might now more easily add additional properties to it which only apply the context if a given tag is present or not present, etc.; see e.g., #467 .)

(Sorry, @gajus , forgot to add this one as a PR first.)

I intend to look next into disabling only the destructured property fixing.

[brettz9]

Btw, I realized we ought to be able to avoid the fixing of duplicates on check-param-names (and check-property-names), so I filed #531 . Not directly related to your request, but thought it may be of interest (esp. since "duplicates" might differ in terms of type or description--an identical name is enough to get the second duplicate removed).

[michaelfarrell76]

wow!!!! unreal turnaround this is so amazing <3 can't wait to check this out!

[gajus]

:tada: This issue has been resolved in version 25.4.0 :tada:

The release is available on:

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

Your semantic-release bot :package::rocket: