Infrastructure: Add eslint-plugin-jsdoc (pull #1647)

* chore: Add ESLint plugin for JSDoc
* fix: ESLint jsdoc/newline-after-description
* fix: ESLint jsdoc/check-tag-names
* fix: ESLint jsdoc/require-param
* fix: ESLint jsdoc/require-returns
* fix: ESLint jsdoc/require-returns-type
* fix: Double word 'value' in comment

.eslintrc.json

@@ -1,5 +1,5 @@
 {
-  "extends": ["eslint:recommended", "plugin:prettier/recommended"],
+  "extends": ["eslint:recommended", "plugin:jsdoc/recommended", "plugin:prettier/recommended"],
   "env": {
     "browser": true,
     "es6": true
@@ -8,6 +8,11 @@
     "ecmaVersion": 6
   },
   "rules": {
+    "jsdoc/no-undefined-types": 0,
+    "jsdoc/require-jsdoc": 0,
+    "jsdoc/require-param-description": 0,
+    "jsdoc/require-param-type": 0,
+    "jsdoc/require-returns-description": 0,
     "strict": [2, "global"],
     "no-console": "error"
   },

examples/alert/js/alert.js

@@ -17,7 +17,7 @@ window.addEventListener('load', function () {
  *
  * @desc Adds an alert to the page
  *
- * @param   {Object}  event  -  Standard W3C event object
+ * @param   {object}  event  -  Standard W3C event object
  *
  */
 

examples/combobox/js/grid-combo-example.js

@@ -90,7 +90,7 @@ function searchVeggies(searchString) {
 
 /**
  * @function onload
- * @desc Initialize the combobox examples once the page has loaded
+ * @description Initialize the combobox examples once the page has loaded
  */
 window.addEventListener('load', function () {
   new aria.GridCombobox(

examples/combobox/js/grid-combo.js

@@ -8,14 +8,12 @@
 var aria = aria || {};
 
 /**
- * @constructor
+ * @class
  *
- * @desc
+ * @description
  *  Combobox object representing the state and interactions for a combobox
  *  widget
  *
- * @param comboboxNode
- *  The DOM node pointing to the combobox
  * @param input
  *  The input node
  * @param grid

examples/dialog-modal/js/dialog.js

@@ -19,11 +19,11 @@ aria.Utils = aria.Utils || {};
   aria.Utils.dialogOpenClass = 'has-dialog';
 
   /**
-   * @desc Set focus on descendant nodes until the first focusable element is
+   * @description Set focus on descendant nodes until the first focusable element is
    *       found.
    * @param element
    *          DOM node for which to find the first focusable descendant.
-   * @returns
+   * @returns {boolean}
    *  true if a focusable element is found and focus is set.
    */
   aria.Utils.focusFirstDescendant = function (element) {
@@ -40,10 +40,10 @@ aria.Utils = aria.Utils || {};
   }; // end focusFirstDescendant
 
   /**
-   * @desc Find the last descendant node that is focusable.
+   * @description Find the last descendant node that is focusable.
    * @param element
    *          DOM node for which to find the last focusable descendant.
-   * @returns
+   * @returns {boolean}
    *  true if a focusable element is found and focus is set.
    */
   aria.Utils.focusLastDescendant = function (element) {
@@ -60,10 +60,10 @@ aria.Utils = aria.Utils || {};
   }; // end focusLastDescendant
 
   /**
-   * @desc Set Attempt to set focus on the current node.
+   * @description Set Attempt to set focus on the current node.
    * @param element
    *          The node to attempt to focus on.
-   * @returns
+   * @returns {boolean}
    *  true if element is focused.
    */
   aria.Utils.attemptFocus = function (element) {
@@ -85,7 +85,7 @@ aria.Utils = aria.Utils || {};
   aria.OpenDialogList = aria.OpenDialogList || new Array(0);
 
   /**
-   * @returns the last opened dialog (the current dialog)
+   * @returns {object} the last opened dialog (the current dialog)
    */
   aria.getCurrentDialog = function () {
     if (aria.OpenDialogList && aria.OpenDialogList.length) {
@@ -114,8 +114,8 @@ aria.Utils = aria.Utils || {};
   document.addEventListener('keyup', aria.handleEscape);
 
   /**
-   * @constructor
-   * @desc Dialog object providing modal focus management.
+   * @class
+   * @description Dialog object providing modal focus management.
    *
    * Assumptions: The element serving as the dialog container is present in the
    * DOM and hidden. The dialog container has role='dialog'.
@@ -235,7 +235,7 @@ aria.Utils = aria.Utils || {};
   };
 
   /**
-   * @desc
+   * @description
    *  Hides the current top dialog,
    *  removes listeners of the top dialog,
    *  restore listeners of a parent dialog if one was open under the one that just closed,
@@ -259,7 +259,7 @@ aria.Utils = aria.Utils || {};
   }; // end close
 
   /**
-   * @desc
+   * @description
    *  Hides the current dialog and replaces it with another.
    *
    * @param newDialogId

examples/feed/js/main.js

@@ -9,8 +9,9 @@
 
 /**
  * ARIA Feed Example
+ *
  * @function onload
- * @desc Initialize the feed once the page has loaded
+ * @description Initialize the feed once the page has loaded
  */
 window.addEventListener('load', function () {
   var feedNode = document.getElementById('restaurant-feed');