Merge pull request #4534 from Polymer/2.0-jsdoc-cleanup

Add eslint for jsdoc and fix issues

.eslintrc.json

@@ -4,7 +4,21 @@
   "rules": {
     "no-console": "off",
     "no-var": "error",
-    "strict": "error"
+    "strict": "error",
+    "valid-jsdoc": ["error", {
+      "requireReturn": false,
+      "prefer": {
+        "arg": "param",
+        "argument": "param",
+        "returns": "return"
+      },
+      "preferType": {
+        "Boolean": "boolean",
+        "Number": "number",
+        "String": "string",
+        "object": "Object"
+      }
+    }]
   },
   "env": {
     "browser": true,

lib/elements/array-selector.html

@@ -193,7 +193,6 @@
       /**
        * Clears the selection state.
        *
-       * @method clearSelection
        */
       clearSelection() {
         // Unbind previous selection
@@ -211,7 +210,6 @@
       /**
        * Returns whether the item is currently selected.
        *
-       * @method isSelected
        * @param {*} item Item from `items` array to test
        * @return {boolean} Whether the item is selected
        */
@@ -222,7 +220,6 @@
       /**
        * Returns whether the item is currently selected.
        *
-       * @method isSelected
        * @param {*} idx Index from `items` array to test
        * @return {boolean} Whether the item is selected
        */
@@ -252,7 +249,6 @@
       /**
        * Deselects the given item if it is already selected.
        *
-       * @method deselect
        * @param {*} item Item from `items` array to deselect
        */
       deselect(item) {
@@ -275,7 +271,6 @@
       /**
        * Deselects the given index if it is already selected.
        *
-       * @method deselect
        * @param {number} idx Index from `items` array to deselect
        */
       deselectIndex(idx) {
@@ -286,7 +281,6 @@
        * Selects the given item.  When `toggle` is true, this will automatically
        * deselect the item if already selected.
        *
-       * @method select
        * @param {*} item Item from `items` array to select
        */
       select(item) {
@@ -297,7 +291,6 @@
        * Selects the given index.  When `toggle` is true, this will automatically
        * deselect the item if already selected.
        *
-       * @method select
        * @param {number} idx Index from `items` array to select
        */
       selectIndex(idx) {

lib/elements/dom-module.html

@@ -54,13 +54,12 @@
     static get observedAttributes() { return ['id'] }
 
     /**
-     * Retrieves the dom specified by `selector` in the module specified by
-     * `id`. For example, this.import('foo', 'img');
-     * @method register
-     * @param {string} id
-     * @param {string=} selector
-     * @return {Element} Returns the dom which matches `selector` in the module
-     * at the specified `id`.
+     * Retrieves the element specified by the css `selector` in the module
+     * registered by `id`. For example, this.import('foo', 'img');
+     * @param {string} id The id of the dom-module in which to search.
+     * @param {string=} selector The css selector by which to find the element.
+     * @return {Element} Returns the element which matches `selector` in the
+     * module registered at the specified `id`.
      */
     static import(id, selector) {
       if (id) {
@@ -108,7 +107,6 @@
      * Registers the dom-module at a given id. This method should only be called
      * when a dom-module is imperatively created. For
      * example, `document.createElement('dom-module').register('foo')`.
-     * @method register
      * @param {string=} id The id at which to register the dom-module.
      */
     register(id) {

lib/elements/dom-repeat.html

@@ -448,8 +448,8 @@
     }
 
     /**
-     * @param {function()} fn
-     * @param {number=} delay
+     * @param {function()} fn Function to debounce.
+     * @param {number=} delay Delay in ms to debounce by.
      */
     __debounceRender(fn, delay) {
       this.__renderDebouncer = Polymer.Debouncer.debounce(
@@ -626,7 +626,6 @@
      * `modelForElement(el).set('item.<sub-prop>', value)`
      * should be used.
      *
-     * @method itemForElement
      * @param {HTMLElement} el Element for which to return the item.
      * @return {*} Item associated with the element.
      */
@@ -640,7 +639,6 @@
      * If `sort` is provided, the index will reflect the sorted order (rather
      * than the original array order).
      *
-     * @method indexForElement
      * @param {HTMLElement} el Element for which to return the index.
      * @return {*} Row index associated with the element (note this may
      *   not correspond to the array index if a user `sort` is applied).
@@ -663,7 +661,6 @@
      *     model.set('item.checked', true);
      *   }
      *
-     * @method modelForElement
      * @param {HTMLElement} el Element for which to return a template model.
      * @return {TemplateInstanceBase} Model representing the binding scope for
      *   the element.

lib/legacy/class.html

@@ -35,8 +35,10 @@
      * to ensure that any legacy behaviors can rely on legacy Polymer API on
      * the underlying element.
      *
-     * @param {Object|Array} behaviors Behavior object or array of behaviors
-     * @param {HTMLElement} klass Element class
+     * @param {Object|Array} behaviors Behavior object or array of behaviors.
+     * @param {HTMLElement} klass Element class.
+     * @return {HTMLElement} Returns a new Element class extended by the
+     * passed in `behaviors` and also by `Polymer.LegacyElementMixin`.
      * @memberof Polymer
      */
     function mixinBehaviors(behaviors, klass) {
@@ -105,9 +107,10 @@
     }
 
     /**
-     * @param {Array} behaviors
-     * @param {Array=} list
-     * @param {Array=} exclude
+     * @param {Array} behaviors List of behaviors to flatten.
+     * @param {Array=} list Target list to flatten behaviors into.
+     * @param {Array=} exclude List of behaviors to exclude from the list.
+     * @return {Array} Returns the list of flattened behaviors.
      */
     function flattenBehaviors(behaviors, list, exclude) {
       list = list || [];