docs: improve jsdoc statements

Author: voxpelli

.eslintrc.json

@@ -8,7 +8,8 @@
     "eslint:recommended",
     "plugin:eslint-plugin/recommended",
     "plugin:n/recommended",
-    "plugin:prettier/recommended"
+    "plugin:prettier/recommended",
+    "plugin:jsdoc/recommended"
   ],
   "rules": {
     "no-var": "error",
@@ -22,6 +23,15 @@
     ],
     "eslint-plugin/prefer-placeholders": "error",
     "eslint-plugin/test-case-shorthand-strings": "error",
-    "prettier/prettier": "error"
+    "prettier/prettier": "error",
+    "jsdoc/check-types": "off",
+    "jsdoc/no-undefined-types": "off",
+    "jsdoc/require-jsdoc": "off",
+    "jsdoc/require-param-description": "off",
+    "jsdoc/require-property-description": "off",
+    "jsdoc/require-returns-description": "off",
+    "jsdoc/require-yields": "off",
+    "jsdoc/tag-lines": ["warn", "never", { "startLines": 1 }],
+    "jsdoc/valid-types": "off"
   }
 }

__tests__/rule-tester.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Helpers for tests.
+ * @file Helpers for tests.
  * @author 唯然<[email protected]>
  */
 'use strict'

package-lock.json

@@ -76,6 +76,7 @@
   },
   "devDependencies": {
     "@types/eslint": "^9.6.0",
+    "@types/estree": "^1.0.5",
     "@types/node": "^18.19.42",
     "@typescript-eslint/parser": "^7.17.0",
     "doctoc": "^2.2.1",
@@ -84,6 +85,7 @@
     "eslint-doc-generator": "^1.7.1",
     "eslint-plugin-eslint-plugin": "^6.2.0",
     "eslint-plugin-jest": "^28.6.0",
+    "eslint-plugin-jsdoc": "^48.8.3",
     "eslint-plugin-n": "^17.9.0",
     "eslint-plugin-prettier": "^5.2.1",
     "globals": "^15.8.0",

package.json

@@ -15,7 +15,10 @@ const getDocsUrl = require('./lib/get-docs-url')
  * @typedef { (FunctionExpression | ArrowFunctionExpression) & { parent: CallExpression }} InlineThenFunctionExpression
  */
 
-/** @param {Node} node */
+/**
+ * @param {Node} node
+ * @returns {boolean}
+ */
 function isFunctionWithBlockStatement(node) {
   if (node.type === 'FunctionExpression') {
     return true
@@ -41,7 +44,10 @@ function isMemberCall(memberName, node) {
   )
 }
 
-/** @param {Node} node */
+/**
+ * @param {Node} node
+ * @returns {boolean}
+ */
 function isFirstArgument(node) {
   return Boolean(
     node.parent && node.parent.arguments && node.parent.arguments[0] === node,
@@ -62,7 +68,9 @@ function isInlineThenFunctionExpression(node) {
 
 /**
  * Checks whether the given node is the last `then()` callback in a promise chain.
+ *
  * @param {InlineThenFunctionExpression} node
+ * @returns {boolean}
  */
 function isLastCallback(node) {
   /** @type {Node} */
@@ -124,7 +132,7 @@ function peek(arr) {
   return arr[arr.length - 1]
 }
 
-module.exports = {
+module.exports = /** @satisfies {import('eslint').Rule.RuleModule} */ ({
   meta: {
     type: 'problem',
     docs: {
@@ -156,7 +164,6 @@ module.exports = {
      *   executing branches ("codePathSegment"s) within the given function
      * @property {Record<string, BranchInfo | undefined>} branchInfoMap This is an object representing information
      *   about all branches within the given function
-     *
      * @typedef {object} BranchInfo
      * @property {boolean} good This is a boolean representing whether
      *   the given branch explicitly `return`s or `throw`s. It starts as `false`
@@ -168,24 +175,25 @@ module.exports = {
 
     /**
      * funcInfoStack is a stack representing the stack of currently executing
-     *   functions
+     * functions
      * example:
-     *   funcInfoStack = [ { branchIDStack: [ 's1_1' ],
-     *       branchInfoMap:
-     *        { s1_1:
-     *           { good: false,
-     *             loc: <loc> } } },
-     *     { branchIDStack: ['s2_1', 's2_4'],
-     *       branchInfoMap:
-     *        { s2_1:
-     *           { good: false,
-     *             loc: <loc> },
-     *          s2_2:
-     *           { good: true,
-     *             loc: <loc> },
-     *          s2_4:
-     *           { good: false,
-     *             loc: <loc> } } } ]
+     * funcInfoStack = [ { branchIDStack: [ 's1_1' ],
+     * branchInfoMap:
+     * { s1_1:
+     * { good: false,
+     * loc: <loc> } } },
+     * { branchIDStack: ['s2_1', 's2_4'],
+     * branchInfoMap:
+     * { s2_1:
+     * { good: false,
+     * loc: <loc> },
+     * s2_2:
+     * { good: true,
+     * loc: <loc> },
+     * s2_4:
+     * { good: false,
+     * loc: <loc> } } } ]
+     *
      * @type {FuncInfo[]}
      */
     const funcInfoStack = []
@@ -257,4 +265,4 @@ module.exports = {
       },
     }
   },
-}
+})