Loosen JSDoc rules

[mcmire]

Currently, all arrow functions and function expressions are required to be documented with JSDoc, and object types in return types are required to documented as well.

This means:

// The arrow function here is now required to be documented
foo(() => {
  // ...
})

foo({
  // The arrow function here is now required to be documented
  bar: () => {
    // ...
  }
})

function foo(): {
  // This is now required to be documented
  bar: string;
} {
  // ...
}

This commit loosens the rules so that:

• Instead of restricting all arrow functions and function expressions, restrict only those that are not contained within plain objects or are not arguments to functions or methods
• Instead of restricting all interfaces or type aliases, restrict only those that do not appear in declare blocks (ambient declarations)
• Instead of restricting object types in return types, restrict object types in "root" types

References

https://consensyssoftware.atlassian.net/browse/WPC-955

---

Note

Low Risk
Low risk: config-only changes that mainly reduce lint noise, though selector-based jsdoc/require-jsdoc tweaks could subtly change what gets flagged in consumer codebases.

Overview
Relaxes jsdoc/require-jsdoc in the base config so arrow functions and function expressions only require JSDoc when they’re not object property values and not callback arguments (via selector-based contexts).

Updates the TypeScript config to build on the base rule instead of replacing it, adding TypeScript-specific contexts to require JSDoc for interfaces/type aliases/enums except inside declare blocks, and for property signatures only on named interfaces/type aliases (not inline object return types). Changelogs and rule snapshots are updated accordingly.

^{Reviewed by Cursor Bugbot for commit 5b07ebc. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mcmire]

This PR was derived directly from MetaMask/create-release-branch#168. The last changes I made to this PR tweaked the rules further. I was hoping to get another review on those changes, but assuming they are good, I planned on integrating them back into this PR. I don't have time to do this right now, but I talked with Mark and he said that he might have time.

@Gudahtt If you do have time, feel free to take over this PR and get it merged.

[mcmire]

While it's true that the base config did apparently require JSDoc for TypeScript symbols, that wasn't true in practice because the JSDoc plugin within the base config doesn't know about TypeScript.

[mcmire]

This changelog entry was missing when 15.0.0 was released. This should list TypeScript symbols for which documentation is required (not the changelog for the base config).

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

[Gudahtt]

Do you have an example for these last two points? I'm not sure that I understand what they mean

[mcmire]

I didn't word this very well, sorry.

Here are some examples for the arrow function entry:

// The arrow function here is no longer required to be documented
foo(() => {
  // ...
})

foo({
  // The arrow function here is no longer required to be documented
  bar: () => {
    // ...
  }
})

[mcmire]

Here are some examples for the interfaces / type aliases entry:

declare module 'prettier' {
  // This is no longer required to be documented
  type Bar = 'baz';

  // This is no longer required to be documented
  export interface Y {
    // whatever
  }
}

Here are some examples for the "object types in return types" entry:

// The object type which is the return type of this function
// is no longer required to be documented
function foo(): {
  bar: 'baz';
  qux: 'blargh';
} {
  return { bar: 'baz', qux: 'blargh' };
}

[mcmire]

I've updated the changelogs so the changes are more clear. I also realized that enums weren't properly scoped so I fixed that as well: d64d667

[Gudahtt]

I am having trouble understanding that last example. What specifically no longer needs to be documented there - what do you mean by "the object type"? We don't document types in JSDoc at all in TypeScript projects - why would any type documentation be needed there in the first place?

[Gudahtt]

Interesting. What is an "inline object return type"?

[mcmire]

Sorry, what I meant is an object type used as a return type which is written inline (not extracted to its own named type).

In code, the change I think I ought to make here is:

function foo(): {
  // We should not require this property to be documented
  bar: 'baz';
} {
  // ...
}

type Foo = {
  // But we should continue to require this property to be documented
  bar: 'baz';
}

Any thoughts on this?

[Gudahtt]

Oh I see, you mean the properties of an object return type. Interesting.

I see what you mean, it is awkward to document properties inline as part of a function signature. I would never expect to be asked to do that. But then again, we do want return types to have docs.

For example if we call that function:

const { bar } = foo();

and hover over bar, it would have no docs at all. Not ideal.

[Gudahtt]

Though if we're unsure at all about a stylistic rule, it would be better to err on the side of loosening it, so I'm still in favour of this (if you find a way to accomplish it that is).

[mcmire]

Okay, this should take care of it. JSDoc will still be required for properties, as long as they are not part of an inline return type: b702649

[mcmire]

Hmm... this might be a breaking change. It seems that the typescript package has been overriding the base package :(

I'll have to double-check this.

[Gudahtt]

Yeah, so it was. It was overwritten by jsdoc.configs['flat/recommended-typescript-error'],.

That's fine, we can include this in v16 instead then

[Gudahtt]

Actually we still need a changelog update to reflect this

[Gudahtt]

LGTM!

Changelog update needed to accurately reflect nature of breaking JSDoc changes in typescript package