Set up ESLint for JSDoc comments (#1605)

* Set up ESLint

* Fix violations

eslint.config.js

@@ -0,0 +1,12 @@
+import jsdoc from "eslint-plugin-jsdoc";
+
+export default [
+  jsdoc.configs["flat/recommended"],
+  {
+    rules: {
+      "jsdoc/require-param-description": "off",
+      "jsdoc/require-returns-description": "off",
+      "jsdoc/tag-lines": ["error", "any", { startLines: 1 }],
+    },
+  },
+];

lib/chai.js

@@ -23,9 +23,9 @@ export {AssertionError};
  *
  * Provides a way to extend the internals of Chai.
  *
- * @param {Function}
+ * @param {Function} fn
  * @returns {this} for chaining
- * @api public
+ * @public
  */
 export function use(fn) {
   const exports = {

lib/chai/assertion.js

@@ -18,37 +18,37 @@ import * as util from './utils/index.js';
  * be assigned during instantiation by passing arguments to this constructor:
  *
  * - `object`: This flag contains the target of the assertion. For example, in
- *   the assertion `expect(numKittens).to.equal(7);`, the `object` flag will
- *   contain `numKittens` so that the `equal` assertion can reference it when
- *   needed.
+ * the assertion `expect(numKittens).to.equal(7);`, the `object` flag will
+ * contain `numKittens` so that the `equal` assertion can reference it when
+ * needed.
  *
  * - `message`: This flag contains an optional custom error message to be
- *   prepended to the error message that's generated by the assertion when it
- *   fails.
+ * prepended to the error message that's generated by the assertion when it
+ * fails.
  *
  * - `ssfi`: This flag stands for "start stack function indicator". It
- *   contains a function reference that serves as the starting point for
- *   removing frames from the stack trace of the error that's created by the
- *   assertion when it fails. The goal is to provide a cleaner stack trace to
- *   end users by removing Chai's internal functions. Note that it only works
- *   in environments that support `Error.captureStackTrace`, and only when
- *   `Chai.config.includeStack` hasn't been set to `false`.
+ * contains a function reference that serves as the starting point for
+ * removing frames from the stack trace of the error that's created by the
+ * assertion when it fails. The goal is to provide a cleaner stack trace to
+ * end users by removing Chai's internal functions. Note that it only works
+ * in environments that support `Error.captureStackTrace`, and only when
+ * `Chai.config.includeStack` hasn't been set to `false`.
  *
  * - `lockSsfi`: This flag controls whether or not the given `ssfi` flag
- *   should retain its current value, even as assertions are chained off of
- *   this object. This is usually set to `true` when creating a new assertion
- *   from within another assertion. It's also temporarily set to `true` before
- *   an overwritten assertion gets called by the overwriting assertion.
+ * should retain its current value, even as assertions are chained off of
+ * this object. This is usually set to `true` when creating a new assertion
+ * from within another assertion. It's also temporarily set to `true` before
+ * an overwritten assertion gets called by the overwriting assertion.
  *
  * - `eql`: This flag contains the deepEqual function to be used by the assertion.
  *
- * @param {Mixed} obj target of the assertion
- * @param {String} msg (optional) custom error message
+ * @param {unknown} obj target of the assertion
+ * @param {string} msg (optional) custom error message
  * @param {Function} ssfi (optional) starting point for removing stack frames
- * @param {Boolean} lockSsfi (optional) whether or not the ssfi flag is locked
- * @api private
+ * @param {boolean} lockSsfi (optional) whether or not the ssfi flag is locked
+ * @returns {unknown}
+ * @private
  */
-
 export function Assertion (obj, msg, ssfi, lockSsfi) {
   util.flag(this, 'ssfi', ssfi || Assertion);
   util.flag(this, 'lockSsfi', lockSsfi);
@@ -111,13 +111,13 @@ Assertion.overwriteChainableMethod = function (name, fn, chainingBehavior) {
  * Executes an expression and check expectations. Throws AssertionError for reporting if test doesn't pass.
  *
  * @name assert
- * @param {Philosophical} expression to be tested
- * @param {String|Function} message or function that returns message to display if expression fails
- * @param {String|Function} negatedMessage or function that returns negatedMessage to display if negated expression fails
- * @param {Mixed} expected value (remember to check for negation)
- * @param {Mixed} actual (optional) will default to `this.obj`
- * @param {Boolean} showDiff (optional) when set to `true`, assert will display a diff in addition to the message if expression fails
- * @api private
+ * @param {unknown} expression to be tested
+ * @param {string | Function} message or function that returns message to display if expression fails
+ * @param {string | Function} negatedMessage or function that returns negatedMessage to display if negated expression fails
+ * @param {unknown} expected value (remember to check for negation)
+ * @param {unknown} actual (optional) will default to `this.obj`
+ * @param {boolean} showDiff (optional) when set to `true`, assert will display a diff in addition to the message if expression fails
+ * @private
  */
 
 Assertion.prototype.assert = function (expr, msg, negateMsg, expected, _actual, showDiff) {
@@ -152,7 +152,7 @@ Assertion.prototype.assert = function (expr, msg, negateMsg, expected, _actual,
  *
  * Quick reference to stored `actual` value for plugin developers.
  *
- * @api private
+ * @private
  */
 Object.defineProperty(Assertion.prototype, '_obj',
   { get: function () {

lib/chai/config.js

@@ -9,10 +9,9 @@ export const config = {
    *
    *     chai.config.includeStack = true;  // enable stack on error
    *
-   * @param {Boolean}
-   * @api public
+   * @param {boolean}
+   * @public
    */
-
   includeStack: false,
 
   /**
@@ -24,10 +23,9 @@ export const config = {
    * will be true when the assertion has requested a diff
    * be shown.
    *
-   * @param {Boolean}
-   * @api public
+   * @param {boolean}
+   * @public
    */
-
   showDiff: true,
 
   /**
@@ -46,10 +44,9 @@ export const config = {
    *
    *     chai.config.truncateThreshold = 0;  // disable truncating
    *
-   * @param {Number}
-   * @api public
+   * @param {number}
+   * @public
    */
-
   truncateThreshold: 40,
 
   /**
@@ -66,10 +63,9 @@ export const config = {
    * This feature is automatically disabled regardless of this config value
    * in environments that don't support proxies.
    *
-   * @param {Boolean}
-   * @api public
+   * @param {boolean}
+   * @public
    */
-
   useProxy: true,
 
   /**
@@ -87,9 +83,8 @@ export const config = {
    *     chai.config.proxyExcludedKeys = ['then', 'inspect'];
    *
    * @param {Array}
-   * @api public
+   * @public
    */
-
   proxyExcludedKeys: ['then', 'catch', 'inspect', 'toJSON'],
 
   /**
@@ -101,20 +96,19 @@ export const config = {
    *
    *     // use a custom comparator
    *     chai.config.deepEqual = (expected, actual) => {
-   *        return chai.util.eql(expected, actual, {
-   *           comparator: (expected, actual) => {
-   *              // for non number comparison, use the default behavior
-   *              if(typeof expected !== 'number') return null;
-   *              // allow a difference of 10 between compared numbers
-   *              return typeof actual === 'number' && Math.abs(actual - expected) < 10
-   *           }
-   *        })
+   *         return chai.util.eql(expected, actual, {
+   *             comparator: (expected, actual) => {
+   *                 // for non number comparison, use the default behavior
+   *                 if(typeof expected !== 'number') return null;
+   *                 // allow a difference of 10 between compared numbers
+   *                 return typeof actual === 'number' && Math.abs(actual - expected) < 10
+   *             }
+   *         })
    *     };
    *
    * @param {Function}
-   * @api public
+   * @public
    */
-
   deepEqual: null
 
 };