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

---

Note

Relaxes JSDoc enforcement for functions and TypeScript symbols, and allows inferred return types for function expressions/arrow functions.

• Base config (packages/base/src/index.mjs):
  • Narrow jsdoc/require-jsdoc:
    • Require for ClassDeclaration, FunctionDeclaration, MethodDefinition.
    • Apply to ArrowFunctionExpression/FunctionExpression only when not inside plain objects or passed as call/new args (:not(Property, NewExpression, CallExpression) > ...).
    • Add coverage for exported variables (ExportNamedDeclaration:has(> VariableDeclaration)).
• TypeScript config (packages/typescript/src/index.mjs):
  • Relax @typescript-eslint/explicit-function-return-type with allowExpressions: true.
  • Override jsdoc/require-jsdoc to include TS symbols and contexts:
    • Interfaces outside declare blocks (:not(TSModuleBlock) > TSInterfaceDeclaration), TSTypeAliasDeclaration, TSEnumDeclaration.
    • Same narrowed contexts for ArrowFunctionExpression/FunctionExpression as base.

^{Written by Cursor Bugbot for commit 85a02f6. This will update automatically on new commits. Configure here.}

[cursor]

TypeScript config missing exported variables JSDoc requirement

The jsdoc/require-jsdoc rule override in the TypeScript config is missing the ExportNamedDeclaration:has(> VariableDeclaration) context that exists in the base config. Since ESLint rule overrides replace rather than merge, this causes exported variables in TypeScript files to not require JSDoc documentation, while they still would in JavaScript files. The context array needs to include this selector to maintain consistency with the base config.

 

[cursor]

Type aliases missing declare block exclusion

The TSTypeAliasDeclaration context selector is missing the :not(TSModuleBlock) > prefix that TSInterfaceDeclaration has. According to the PR description, both interfaces and type aliases in declare blocks should not require JSDoc documentation, but this omission means type aliases within declare blocks will still incorrectly require JSDoc.

 

[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.