feat(ts-method-signature-style): add new rule

.README/README.md

@@ -278,6 +278,7 @@ Finally, enable all of the rules that you would like to use.
  "jsdoc/sort-tags": 1,
  "jsdoc/tag-lines": 1, // Recommended
  "jsdoc/text-escaping": 1,
+ "jsdoc/ts-method-signature-style": 1,
  "jsdoc/type-formatting": 1,
  "jsdoc/valid-types": 1 // Recommended
  }

.README/rules/ts-method-signature-style.md

@@ -0,0 +1,26 @@
+# `ts-method-signature-style`
+
+Inspired by `typescript-eslint`'s [method-signature-style](https://typescript-eslint.io/rules/method-signature-style/) rule.
+
+See that rule for the rationale behind preferring the function
+property.
+
+## Options
+
+{"gitdown": "options"}
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|``|
+|Recommended|false|
+|Settings||
+|Options|string ("method", "property") followed by object with `enableFixer`|
+
+## Failing examples
+
+<!-- assertions-failing tsMethodSignatureStyle -->
+
+## Passing examples
+
+<!-- assertions-passing tsMethodSignatureStyle -->

README.md

@@ -305,6 +305,7 @@ Finally, enable all of the rules that you would like to use.
  "jsdoc/sort-tags": 1,
  "jsdoc/tag-lines": 1, // Recommended
  "jsdoc/text-escaping": 1,
+ "jsdoc/ts-method-signature-style": 1,
  "jsdoc/type-formatting": 1,
  "jsdoc/valid-types": 1 // Recommended
  }
@@ -497,5 +498,6 @@ non-default-recommended fixer).
 ||:wrench:| [sort-tags](./docs/rules/sort-tags.md#readme) | Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups. |
 |:heavy_check_mark:|:wrench:| [tag-lines](./docs/rules/tag-lines.md#readme) | Enforces lines (or no lines) before, after, or between tags. |
 ||:wrench:| [text-escaping](./docs/rules/text-escaping.md#readme) | Auto-escape certain characters that are input within block and tag descriptions. |
+||:wrench:| [ts-method-signature-style](./docs/rules/ts-method-signature-style.md#readme) | Prefers either function properties or method signatures |
 ||:wrench:| [type-formatting](./docs/rules/type-formatting.md#readme) | Formats JSDoc type values. |
 |:heavy_check_mark:|| [valid-types](./docs/rules/valid-types.md#readme) | Requires all types/namepaths to be valid JSDoc, Closure compiler, or TypeScript types (configurable in settings). |

docs/rules/ts-method-signature-style.md

@@ -0,0 +1,163 @@
+<a name="user-content-ts-method-signature-style"></a>
+<a name="ts-method-signature-style"></a>
+# <code>ts-method-signature-style</code>
+
+Inspired by `typescript-eslint`'s [method-signature-style](https://typescript-eslint.io/rules/method-signature-style/) rule.
+
+See that rule for the rationale behind preferring the function
+property.
+
+<a name="user-content-ts-method-signature-style-options"></a>
+<a name="ts-method-signature-style-options"></a>
+## Options
+
+The first option is a string with the following possible values: "method", "property".
+
+
+The next option is an object with the following properties.
+
+<a name="user-content-ts-method-signature-style-options-enablefixer"></a>
+<a name="ts-method-signature-style-options-enablefixer"></a>
+### <code>enableFixer</code>
+
+Whether to enable the fixer. Defaults to `true`.
+
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|``|
+|Recommended|false|
+|Settings||
+|Options|string ("method", "property") followed by object with `enableFixer`|
+
+<a name="user-content-ts-method-signature-style-failing-examples"></a>
+<a name="ts-method-signature-style-failing-examples"></a>
+## Failing examples
+
+The following patterns are considered problems:
+
+````ts
+/**
+ * @param {{
+ * func(arg: string): number
+ * }} someName
+ */
+// "jsdoc/ts-method-signature-style": ["error"|"warn", "property"]
+// Message: Found method signature; prefer function property.
+
+/**
+ * @param {{
+ * func(arg: string): number
+ * }} someName
+ */
+// "jsdoc/ts-method-signature-style": ["error"|"warn", "property",{"enableFixer":false}]
+// Message: Found method signature; prefer function property.
+
+/**
+ * @param {{
+ * func(arg: number): void
+ * func(arg: string): void
+ * func(arg: boolean): void
+ * }} someName
+ */
+// Message: Found method signature; prefer function property.
+
+/**
+ * @param {{
+ * func: (arg: string) => number
+ * }} someName
+ */
+// "jsdoc/ts-method-signature-style": ["error"|"warn", "method"]
+// Message: Found function property; prefer method signature.
+
+/**
+ * @param {{
+ * func: (arg: string) => number
+ * }} someName
+ */
+// "jsdoc/ts-method-signature-style": ["error"|"warn", "method",{"enableFixer":false}]
+// Message: Found function property; prefer method signature.
+
+/**
+ * @type {{
+ * func: ((arg: number) => void) &
+ * ((arg: string) => void) &
+ * ((arg: boolean) => void)
+ * }}
+ */
+// "jsdoc/ts-method-signature-style": ["error"|"warn", "method"]
+// Message: Found function property; prefer method signature.
+
+/**
+ * @param {{
+ * func: ((arg: number) => void) &
+ * ((arg: string) => void) &
+ * ((arg: boolean) => void)
+ * }} someName
+ */
+// "jsdoc/ts-method-signature-style": ["error"|"warn", "method",{"enableFixer":false}]
+// Message: Found function property; prefer method signature.
+
+/**
+ * @param {{
+ * "func"(arg: string): number
+ * }} someName
+ */
+// "jsdoc/ts-method-signature-style": ["error"|"warn", "property"]
+// Message: Found method signature; prefer function property.
+
+/**
+ * @param {{
+ * 'func': (arg: string) => number
+ * }} someName
+ */
+// "jsdoc/ts-method-signature-style": ["error"|"warn", "method"]
+// Message: Found function property; prefer method signature.
+
+/** @type {{
+ * func: ((arg: number) => void) &
+ * ((arg: string) => void) &
+ * ((arg: boolean) => void)
+ * }}
+ */
+// "jsdoc/ts-method-signature-style": ["error"|"warn", "method"]
+// Message: Found function property; prefer method signature.
+````
+
+
+
+<a name="user-content-ts-method-signature-style-passing-examples"></a>
+<a name="ts-method-signature-style-passing-examples"></a>
+## Passing examples
+
+The following patterns are not considered problems:
+
+````ts
+/**
+ * @param {{
+ * func: (arg: string) => number
+ * }}
+ */
+// "jsdoc/ts-method-signature-style": ["error"|"warn", "property"]
+
+/**
+ * @param {{
+ * func: ((arg: number) => void) &
+ * ((arg: string) => void) &
+ * ((arg: boolean) => void)
+ * }}
+ */
+
+/**
+ * @param {abc<}
+ */
+
+/**
+ * @param {{
+ * func: ((arg: number) => void) & (SomeType)
+ * }}
+ */
+// "jsdoc/ts-method-signature-style": ["error"|"warn", "method"]
+````
+

package.json

@@ -5,7 +5,7 @@
  "url": "http://gajus.com"
  },
  "dependencies": {
- "@es-joy/jsdoccomment": "~0.75.0",
+ "@es-joy/jsdoccomment": "~0.76.0",
  "are-docs-informative": "^0.0.2",
  "comment-parser": "1.4.1",
  "debug": "^4.4.3",
@@ -58,7 +58,7 @@
  "glob": "^11.0.3",
  "globals": "^16.4.0",
  "husky": "^9.1.7",
- "jsdoc-type-pratt-parser": "^6.9.1",
+ "jsdoc-type-pratt-parser": "^6.10.0",
  "json-schema": "^0.4.0",
  "json-schema-to-typescript": "^15.0.4",
  "lint-staged": "^16.2.3",

src/index-cjs.js

@@ -66,6 +66,7 @@ import requireYieldsCheck from './rules/requireYieldsCheck.js';
 import sortTags from './rules/sortTags.js';
 import tagLines from './rules/tagLines.js';
 import textEscaping from './rules/textEscaping.js';
+import tsMethodSignatureStyle from './rules/tsMethodSignatureStyle.js';
 import typeFormatting from './rules/typeFormatting.js';
 import validTypes from './rules/validTypes.js';
 
@@ -251,6 +252,7 @@ index.rules = {
  'sort-tags': sortTags,
  'tag-lines': tagLines,
  'text-escaping': textEscaping,
+ 'ts-method-signature-style': tsMethodSignatureStyle,
  'type-formatting': typeFormatting,
  'valid-types': validTypes,
 };
@@ -341,6 +343,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
  'jsdoc/sort-tags': 'off',
  'jsdoc/tag-lines': warnOrError,
  'jsdoc/text-escaping': 'off',
+ 'jsdoc/ts-method-signature-style': 'off',
  'jsdoc/type-formatting': 'off',
  'jsdoc/valid-types': warnOrError,
  },

src/index.js

@@ -72,6 +72,7 @@ import requireYieldsCheck from './rules/requireYieldsCheck.js';
 import sortTags from './rules/sortTags.js';
 import tagLines from './rules/tagLines.js';
 import textEscaping from './rules/textEscaping.js';
+import tsMethodSignatureStyle from './rules/tsMethodSignatureStyle.js';
 import typeFormatting from './rules/typeFormatting.js';
 import validTypes from './rules/validTypes.js';
 
@@ -257,6 +258,7 @@ index.rules = {
  'sort-tags': sortTags,
  'tag-lines': tagLines,
  'text-escaping': textEscaping,
+ 'ts-method-signature-style': tsMethodSignatureStyle,
  'type-formatting': typeFormatting,
  'valid-types': validTypes,
 };
@@ -347,6 +349,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
  'jsdoc/sort-tags': 'off',
  'jsdoc/tag-lines': warnOrError,
  'jsdoc/text-escaping': 'off',
+ 'jsdoc/ts-method-signature-style': 'off',
  'jsdoc/type-formatting': 'off',
  'jsdoc/valid-types': warnOrError,
  },