Fix ESLint errors and JSDoc comments in linters

test/linter/index.js

@@ -1,3 +1,6 @@
+/* Any copyright is dedicated to the Public Domain.
+ * http://creativecommons.org/publicdomain/zero/1.0/ */
+
 'use strict';
 const testBrowsers = require('./test-browsers.js');
 const testLinks = require('./test-links.js');

test/linter/test-browsers.js

@@ -1,3 +1,6 @@
+/* Any copyright is dedicated to the Public Domain.
+ * http://creativecommons.org/publicdomain/zero/1.0/ */
+
 'use strict';
 const path = require('path');
 const chalk = require('chalk');
@@ -7,7 +10,7 @@ const chalk = require('chalk');
  * @typedef {import('../utils').Logger} Logger
  */
 
-/** @type {Record<string, string[]>} */
+/** @type {object.<string, string[]>} */
 const browsers = {
   desktop: ['chrome', 'edge', 'firefox', 'ie', 'opera', 'safari'],
   mobile: [
@@ -27,22 +30,24 @@ const browsers = {
 };
 
 /**
- * @param {Identifier} data
- * @param {string[]} displayBrowsers
- * @param {string[]} requiredBrowsers
- * @param {string} category
- * @param {Logger} logger
- * @param {string} [path]
- * @returns {boolean}
+ * Check the data for any disallowed browsers or if it's missing required browsers
+ *
+ * @param {Identifier} data The data to test
+ * @param {string[]} displayBrowsers All of the allowed browsers for this data
+ * @param {string[]} requiredBrowsers All of the required browsers for this data
+ * @param {string} category The category the data belongs to
+ * @param {Logger} logger The logger to output errors to
+ * @param {string} [path] The path of the data
+ * @returns {void}
  */
-function processData(
+const processData = (
   data,
   displayBrowsers,
   requiredBrowsers,
   category,
   logger,
   path = '',
-) {
+) => {
   if (data.__compat && data.__compat.support) {
     const support = data.__compat.support;
 
@@ -72,10 +77,6 @@ function processData(
       const statementList = Array.isArray(supportStatement)
         ? supportStatement
         : [supportStatement];
-      function hasVersionAddedOnly(statement) {
-        const keys = Object.keys(statement);
-        return keys.length === 1 && keys[0] === 'version_added';
-      }
       let sawVersionAddedOnly = false;
       for (const statement of statementList) {
         if (hasVersionAddedOnly(statement)) {
@@ -103,13 +104,26 @@ function processData(
       path && path.length > 0 ? `${path}.${key}` : key,
     );
   }
-}
+};
+
+/**
+ * Checks a support statement and identifies whether it only has 'version_added'
+ *
+ * @param {Identifier} statement The support statement to check
+ * @returns {boolean} If the statement only has 'version_added'
+ */
+const hasVersionAddedOnly = statement => {
+  const keys = Object.keys(statement);
+  return keys.length === 1 && keys[0] === 'version_added';
+};
 
 /**
- * @param {string} filename
+ * Test for issues within the browsers in the data within the specified file
+ *
+ * @param {string} filename The file to test
  * @returns {boolean} If the file contains errors
  */
-function testBrowsers(filename) {
+const testBrowsers = filename => {
   const relativePath = path.relative(
     path.resolve(__dirname, '..', '..'),
     filename,
@@ -145,7 +159,11 @@ function testBrowsers(filename) {
   /** @type {string[]} */
   const errors = [];
   const logger = {
-    /** @param {...unknown} message */
+    /**
+     * logger.error
+     *
+     * @param {...*} message Messages to add to errors
+     */
     error: (...message) => {
       errors.push(message.join(' '));
     },
@@ -165,6 +183,6 @@ function testBrowsers(filename) {
     return true;
   }
   return false;
-}
+};
 
 module.exports = testBrowsers;

test/linter/test-consistency.js

@@ -1,5 +1,7 @@
+/* Any copyright is dedicated to the Public Domain.
+ * http://creativecommons.org/publicdomain/zero/1.0/ */
+
 'use strict';
-const path = require('path');
 const compareVersions = require('compare-versions');
 const chalk = require('chalk');
 
@@ -15,15 +17,15 @@ const chalk = require('chalk');
  * @typedef {'unsupported' | 'support_unknown' | 'subfeature_earlier_implementation'} ErrorType
  *
  * @typedef {object} ConsistencyError
- * @property {string} feature
- * @property {string[]} path
- * @property {FeatureError[]} errors
+ * @property {string} feature The identifier of the feature
+ * @property {string[]} path The path of the feature
+ * @property {FeatureError[]} errors Any errors found
  *
  * @typedef {object} FeatureError
- * @property {ErrorType} errortype
- * @property {string} browser
- * @property {VersionValue} parent_value
- * @property {[string, VersionValue][]} subfeatures
+ * @property {ErrorType} errortype The type of the error
+ * @property {string} browser The browser the error was found
+ * @property {VersionValue} parent_value The value of the parent feature
+ * @property {[string, VersionValue][]} subfeatures The versions of the subfeatures
  */
 
 /**
@@ -34,17 +36,21 @@ const chalk = require('chalk');
  */
 class ConsistencyChecker {
   /**
-   * @param {Identifier} data
-   * @return {ConsistencyError[]}
+   * Checks the data for any errors
+   *
+   * @param {Identifier} data The data to test
+   * @returns {ConsistencyError[]} Any errors found within the data
    */
   check(data) {
     return this.checkSubfeatures(data);
   }
 
   /**
-   * @param {Identifier} data
-   * @param {string[]} [path]
-   * @return {ConsistencyError[]}
+   * Recursively checks the data for any errors
+   *
+   * @param {Identifier} data The data to test
+   * @param {string[]} [path] The path of the data
+   * @returns {ConsistencyError[]} Any errors found within the data
    */
   checkSubfeatures(data, path = []) {
     /** @type {ConsistencyError[]} */
@@ -78,8 +84,10 @@ class ConsistencyChecker {
   }
 
   /**
-   * @param {PrimaryIdentifier & Required<IdentifierMeta>} data
-   * @return {FeatureError[]}
+   * Checks a specific feature for errors
+   *
+   * @param {Identifier} data The data to test
+   * @returns {FeatureError[]} Any errors found within the data
    */
   checkFeature(data) {
     /** @type {FeatureError[]} */
@@ -92,7 +100,7 @@ class ConsistencyChecker {
     // Test whether sub-features are supported when basic support is not implemented
     // For all unsupported browsers (basic support == false), sub-features should be set to false
     const unsupportedInParent = this.extractUnsupportedBrowsers(data.__compat);
-    /** @type {Partial<Record<string, [string, VersionValue][]>>} */
+    /** @type {?object.<string, string[]|VersionValue[]>} */
     var inconsistentSubfeaturesByBrowser = {};
 
     subfeatures.forEach(subfeature => {
@@ -217,16 +225,20 @@ class ConsistencyChecker {
   }
 
   /**
-   * @param {Identifier} data
-   * @return {data is Required<IdentifierMeta>}
+   * Checks if the data is a feature
+   *
+   * @param {Identifier} data The data to test
+   * @returns {boolean} If the data is a feature statement
    */
   isFeature(data) {
     return '__compat' in data;
   }
 
   /**
-   * @param {CompatStatement} compatData
-   * @return {string[]}
+   * Get all of the unsupported browsers in a feature
+   *
+   * @param {CompatStatement} compatData The compat data to process
+   * @returns {string[]} The list of browsers marked as unsupported
    */
   extractUnsupportedBrowsers(compatData) {
     return this.extractBrowsers(
@@ -239,8 +251,10 @@ class ConsistencyChecker {
   }
 
   /**
-   * @param {CompatStatement} compatData
-   * @return {string[]}
+   * Get all of the browsers with unknown support in a feature
+   *
+   * @param {CompatStatement} compatData The compat data to process
+   * @returns {string[]} The list of browsers with unknown support
    */
   extractSupportUnknownBrowsers(compatData) {
     return this.extractBrowsers(
@@ -250,8 +264,10 @@ class ConsistencyChecker {
   }
 
   /**
-   * @param {CompatStatement} compatData
-   * @return {string[]}
+   * Get all of the browsers with either unknown or no support in a feature
+   *
+   * @param {CompatStatement} compatData The compat data to process
+   * @returns {string[]} The list of browsers with non-truthy (false or null) support
    */
   extractSupportNotTrueBrowsers(compatData) {
     return this.extractBrowsers(
@@ -264,8 +280,10 @@ class ConsistencyChecker {
     );
   }
   /**
-   * @param {CompatStatement} compatData
-   * @return {string[]}
+   * Get all of the browsers with a version number in a feature
+   *
+   * @param {CompatStatement} compatData The compat data to process
+   * @returns {string[]} The list of browsers with an exact version number
    */
   extractSupportedBrowsersWithVersion(compatData) {
     return this.extractBrowsers(
@@ -275,11 +293,13 @@ class ConsistencyChecker {
   }
 
   /**
-   * @param {SupportStatement} compatData
-   * @return {string | null}
+   * Get the version added for a feature or recursively search the array for the earliest version
+   *
+   * @param {SupportStatement} compatData The compat data to process
+   * @returns {?string} The earliest version added in the data
    */
   getVersionAdded(compatData) {
-    /** @type {string | null} */
+    /** @type {?string} */
     var version_added = null;
 
     if (typeof compatData.version_added === 'string')
@@ -307,9 +327,11 @@ class ConsistencyChecker {
   }
 
   /**
-   * @param {SupportStatement} a
-   * @param {SupportStatement} b
-   * @return {boolean}
+   * Compare two versions and determine if a's version is greater (later) than b's version
+   *
+   * @param {SupportStatement} a The first support statement to compare
+   * @param {SupportStatement} b The second support statement to compare
+   * @returns {boolean} If a's version is greater (later) than b's version
    */
   isVersionAddedGreater(a, b) {
     var a_version_added = this.getVersionAdded(a);
@@ -329,10 +351,11 @@ class ConsistencyChecker {
   }
 
   /**
+   * Get all of the browsers within the data and send the data to the callback
    *
-   * @param {CompatStatement} compatData
-   * @param {(browserData: SimpleSupportStatement) => boolean} callback
-   * @return {string[]}
+   * @param {CompatStatement} compatData The compat data to process
+   * @param {(browserData: SimpleSupportStatement) => boolean} callback The function to send the data to
+   * @returns {*} The response of the callback, or "false"
    */
   extractBrowsers(compatData, callback) {
     return Object.keys(compatData.support).filter(browser => {
@@ -350,9 +373,12 @@ class ConsistencyChecker {
 }
 
 /**
- * @param {string} filename
+ * Test the version consistency within the file
+ *
+ * @param {string} filename The file to test
+ * @returns {boolean} If the file contains errors
  */
-function testConsistency(filename) {
+const testConsistency = filename => {
   /** @type {Identifier} */
   let data = require(filename);
 
@@ -398,6 +424,6 @@ function testConsistency(filename) {
     return true;
   }
   return false;
-}
+};
 
 module.exports = testConsistency;