Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Set up ESLint for JSDoc comments #1605

Merged
merged 2 commits into from
Feb 19, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions eslint.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
import jsdoc from "eslint-plugin-jsdoc";

export default [
jsdoc.configs["flat/recommended"],
Copy link
Contributor

@43081j 43081j Feb 19, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

while you're in there, can you maybe also enable eslint's recommended rule set? im surprised we didn't already have eslint

if it ends up with too big of a change, you could do a PR to add eslint + recommended, then a separate one for jsdoc on top or vice versa

{
rules: {
"jsdoc/require-param-description": "off",
"jsdoc/require-returns-description": "off",
"jsdoc/tag-lines": ["error", "any", { startLines: 1 }],
},
},
];
4 changes: 2 additions & 2 deletions lib/chai.js
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand Down
56 changes: 28 additions & 28 deletions lib/chai/assertion.js
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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 () {
Expand Down
42 changes: 18 additions & 24 deletions lib/chai/config.js
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,9 @@ export const config = {
*
* chai.config.includeStack = true; // enable stack on error
*
* @param {Boolean}
* @api public
* @param {boolean}
* @public
*/

includeStack: false,

/**
Expand All @@ -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,

/**
Expand All @@ -46,10 +44,9 @@ export const config = {
*
* chai.config.truncateThreshold = 0; // disable truncating
*
* @param {Number}
* @api public
* @param {number}
* @public
*/

truncateThreshold: 40,

/**
Expand All @@ -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,

/**
Expand All @@ -87,9 +83,8 @@ export const config = {
* chai.config.proxyExcludedKeys = ['then', 'inspect'];
*
* @param {Array}
* @api public
* @public
*/

proxyExcludedKeys: ['then', 'catch', 'inspect', 'toJSON'],

/**
Expand All @@ -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

};
Loading