chore: describe disable comments

dfahlander · Aug 3, 2024 · ebcf63e · ebcf63e
1 parent 4bbfe79
commit ebcf63e
Show file tree

Hide file tree

Showing 4 changed files with 36 additions and 31 deletions.
diff --git a/eslint.config.js b/eslint.config.js
@@ -23,7 +23,6 @@ const mainRules = {
     '@typescript-eslint/no-extraneous-class': 0,
 
     // Disable for now
-    '@eslint-community/eslint-comments/require-description': 0,
     'jsdoc/check-types': 0,
 
     '@stylistic/brace-style': 'off',

diff --git a/test/test.js b/test/test.js
@@ -2,7 +2,7 @@
     jsdoc/require-jsdoc, no-empty-function, no-shadow,
     jsdoc/no-bad-blocks,
     @typescript-eslint/no-misused-promises,
-    @typescript-eslint/no-floating-promises
+    @typescript-eslint/no-floating-promises -- Testing
     */
 
 import {describe, it} from 'mocha';
@@ -2071,8 +2071,8 @@ describe('Typeson', function () {
                 }
             }).register([sparseUndefined]);
 
-            // eslint-disable-next-line @stylistic/max-len
-            // eslint-disable-next-line no-sparse-arrays, @stylistic/comma-dangle, @stylistic/array-bracket-spacing
+            // eslint-disable-next-line @stylistic/max-len -- Long
+            // eslint-disable-next-line no-sparse-arrays, @stylistic/comma-dangle, @stylistic/array-bracket-spacing -- Deliberately sparse
             const arr = [, 5, , , 6, ];
             let tson = typeson.stringify(arr);
             log(tson);
@@ -2090,8 +2090,8 @@ describe('Typeson', function () {
             // Once again for coverage of absent observer and
             //  nested keypath
             typeson = new Typeson().register([sparseUndefined]);
-            // eslint-disable-next-line @stylistic/max-len
-            // eslint-disable-next-line no-sparse-arrays, @stylistic/comma-dangle, @stylistic/array-bracket-spacing
+            // eslint-disable-next-line @stylistic/max-len -- Long
+            // eslint-disable-next-line no-sparse-arrays, @stylistic/comma-dangle, @stylistic/array-bracket-spacing -- Deliberately sparse
             const arr2 = {a: [, 5, , , 6, ]};
             tson = typeson.stringify(arr2);
             log(tson);
@@ -2135,8 +2135,8 @@ describe('Typeson', function () {
                 }
             }).register([sparseUndefined]);
 
-            // eslint-disable-next-line @stylistic/max-len
-            // eslint-disable-next-line no-sparse-arrays, @stylistic/comma-dangle, @stylistic/array-bracket-spacing
+            // eslint-disable-next-line @stylistic/max-len -- Long
+            // eslint-disable-next-line no-sparse-arrays, @stylistic/comma-dangle, @stylistic/array-bracket-spacing -- Deliberately sparse
             const arr = [, 5, , , 6, ];
             let tson = typeson.stringify(arr);
             log(tson);
@@ -2154,8 +2154,8 @@ describe('Typeson', function () {
             // Once again for coverage of absent observer and
             //  nested keypath
             typeson = new Typeson().register([sparseUndefined]);
-            // eslint-disable-next-line @stylistic/max-len
-            // eslint-disable-next-line no-sparse-arrays, @stylistic/comma-dangle, @stylistic/array-bracket-spacing
+            // eslint-disable-next-line @stylistic/max-len -- Long
+            // eslint-disable-next-line no-sparse-arrays, @stylistic/comma-dangle, @stylistic/array-bracket-spacing -- Deliberately sparse
             const arr2 = {a: [, 5, , , 6, ]};
             tson = typeson.stringify(arr2);
             log(tson);
@@ -2203,8 +2203,8 @@ describe('Typeson', function () {
                 }
             }).register([sparseUndefined]);
 
-            // eslint-disable-next-line @stylistic/max-len
-            // eslint-disable-next-line no-sparse-arrays, @stylistic/comma-dangle, @stylistic/array-bracket-spacing
+            // eslint-disable-next-line @stylistic/max-len -- Long
+            // eslint-disable-next-line no-sparse-arrays, @stylistic/comma-dangle, @stylistic/array-bracket-spacing -- Deliberately sparse
             const arr = [, 5, , , 6, ];
             let tson = await typeson.stringifyAsync(arr);
             log(tson);
@@ -2222,8 +2222,8 @@ describe('Typeson', function () {
             // Once again for coverage of absent observer and
             //  nested keypath
             typeson = new Typeson().register([sparseUndefined]);
-            // eslint-disable-next-line @stylistic/max-len
-            // eslint-disable-next-line no-sparse-arrays, @stylistic/comma-dangle, @stylistic/array-bracket-spacing
+            // eslint-disable-next-line @stylistic/max-len -- Long
+            // eslint-disable-next-line no-sparse-arrays, @stylistic/comma-dangle, @stylistic/array-bracket-spacing -- Deliberately sparse
             const arr2 = {a: [, 5, , , 6, ]};
             tson = await typeson.stringifyAsync(arr2);
             log(tson);
@@ -3477,26 +3477,26 @@ describe('TypesonPromise', function () {
             /** @type {(value?: any) => void}} */
             resolve
         ) {
-            // eslint-disable-next-line promise/catch-or-return
+            // eslint-disable-next-line promise/catch-or-return -- Not a promise
             TypesonPromise.all([
                 ...makePromises(),
                 100,
                 null,
                 function () {}
             ]).then(function (results) {
                 assert(
-                    // eslint-disable-next-line promise/always-return
                     results[0] === 30 && results[1] === 400 &&
                         results[2] === 20 &&
                         results[3] === 100 && results[4] === null &&
                         typeof results[5] === 'function',
                     'Should work with Promise.all'
                 );
+                return undefined;
             }).then(function () {
                 return TypesonPromise.race(
                     makePromises()
                 // eslint-disable-next-line @stylistic/max-len -- Long
-                // eslint-disable-next-line promise/always-return, promise/no-nesting
+                // eslint-disable-next-line promise/always-return, promise/no-nesting -- Not a promise
                 ).then(function (results) {
                     assert(
                         results === 400,
@@ -3511,10 +3511,10 @@ describe('TypesonPromise', function () {
                             rej('foo');
                         }, 10);
                     })
-                // eslint-disable-next-line promise/no-nesting
+                // eslint-disable-next-line @stylistic/max-len -- Long
+                // eslint-disable-next-line promise/no-nesting -- Not a regular promise
                 ]).then(function (results) {
                     assert(
-                        // eslint-disable-next-line promise/always-return
                         results[0].status === 'fulfilled' &&
                         results[0].value === 30 &&
                         results[1].status === 'fulfilled' &&
@@ -3527,6 +3527,7 @@ describe('TypesonPromise', function () {
                     );
 
                     resolve();
+                    return undefined;
                 });
             });
         });
@@ -3546,7 +3547,7 @@ describe('TypesonPromise', function () {
             });
             return [x, y];
         }
-        // eslint-disable-next-line promise/avoid-new
+        // eslint-disable-next-line promise/avoid-new -- Own API
         return new Promise(function (
             /** @type {(value?: any) => void} */
             resolve

diff --git a/typeson.js b/typeson.js
@@ -773,7 +773,7 @@ class Typeson {
                 _ret = replaced;
                 observerData = {replaced};
             } else {
-                // eslint-disable-next-line no-lonely-if
+                // eslint-disable-next-line no-lonely-if -- Clearer
                 if (keypath === '' &&
                     hasConstructorOf(value, TypesonPromise)
                 ) {
@@ -822,7 +822,8 @@ class Typeson {
 
             // Iterate object or array
             if (_stateObj.iterateIn) {
-                // eslint-disable-next-line guard-for-in
+                // eslint-disable-next-line @stylistic/max-len -- Long
+                // eslint-disable-next-line guard-for-in -- Guard not wanted here
                 for (const key in value) {
                     const ownKeysObj = {ownKeys: hasOwn(value, key)};
                     _adaptBuiltinStateObjectProperties(
@@ -1581,13 +1582,15 @@ class Typeson {
     }
 }
 
+/* eslint-disable @stylistic/max-len -- Long */
 /**
  * We keep this function minimized so if using two instances of this
  * library, where one is minimized and one is not, it will still work
  * with `hasConstructorOf`.
  * @class
  */
-class Undefined{} // eslint-disable-line @stylistic/space-before-blocks
+class Undefined{} // eslint-disable-line @stylistic/space-before-blocks -- For minimizing
+/* eslint-enable @stylistic/max-len -- Long */
 
 // eslint-disable-next-line camelcase -- Special identifier
 Undefined.__typeson__type__ = 'TypesonUndefined';

diff --git a/utils/TypesonPromise.js b/utils/TypesonPromise.js
@@ -1,4 +1,4 @@
-/* eslint-disable promise/avoid-new */
+/* eslint-disable promise/avoid-new -- Own API */
 /**
  * We keep this function minimized so if using two instances of this
  *   library, where one is minimized and one is not, it will still work
@@ -19,9 +19,9 @@ class TypesonPromise {
     }
 }
 
-/* eslint-enable promise/avoid-new */
+/* eslint-enable promise/avoid-new -- Own API */
 
-// eslint-disable-next-line @stylistic/max-len
+// eslint-disable-next-line @stylistic/max-len -- Long
 // class TypesonPromise extends Promise {get[Symbol.toStringTag](){return 'TypesonPromise'};} // eslint-disable-line keyword-spacing, space-before-function-paren, space-before-blocks, block-spacing, semi
 
 // eslint-disable-next-line camelcase -- Special identifier
@@ -47,9 +47,11 @@ if (typeof Symbol !== 'undefined') {
  */
 TypesonPromise.prototype.then = function (onFulfilled, onRejected) {
     return new TypesonPromise((typesonResolve, typesonReject) => {
-        // eslint-disable-next-line promise/catch-or-return
+        // eslint-disable-next-line @stylistic/max-len -- Long
+        // eslint-disable-next-line promise/catch-or-return -- Handling ourselves
         this.p.then(function (res) {
-            // eslint-disable-next-line promise/always-return
+            // eslint-disable-next-line @stylistic/max-len -- Long
+            // eslint-disable-next-line promise/always-return -- Handle ourselves
             typesonResolve(onFulfilled ? onFulfilled(res) : res);
         }).catch(function (/** @type {unknown} */ res) {
             return onRejected
@@ -101,7 +103,7 @@ TypesonPromise.reject = function (v) {
  */
 TypesonPromise.all = function (promArr) {
     return new TypesonPromise(function (typesonResolve, typesonReject) {
-        // eslint-disable-next-line promise/catch-or-return
+        // eslint-disable-next-line promise/catch-or-return -- Handle ourselves
         Promise.all(promArr.map((prom) => {
             return prom?.constructor &&
                 '__typeson__type__' in prom.constructor &&
@@ -119,7 +121,7 @@ TypesonPromise.all = function (promArr) {
  */
 TypesonPromise.race = function (promArr) {
     return new TypesonPromise(function (typesonResolve, typesonReject) {
-        // eslint-disable-next-line promise/catch-or-return
+        // eslint-disable-next-line promise/catch-or-return -- Handle ourselves
         Promise.race(promArr.map((prom) => {
             return prom?.constructor &&
                 '__typeson__type__' in prom.constructor &&
@@ -137,7 +139,7 @@ TypesonPromise.race = function (promArr) {
  */
 TypesonPromise.allSettled = function (promArr) {
     return new TypesonPromise(function (typesonResolve, typesonReject) {
-        // eslint-disable-next-line promise/catch-or-return
+        // eslint-disable-next-line promise/catch-or-return -- Handle ourselves
         Promise.allSettled(promArr.map((prom) => {
             return prom?.constructor &&
                 '__typeson__type__' in prom.constructor &&