docs(jsdoc): Add docs, standardize (#1593)

Adds JSDoc comments for a couple of methods, @returns everywhere it was missing and introduces some additional lints. Also introduces a Prettier plugin to automatically format all JSDoc comments.

.eslintrc.json

@@ -3,17 +3,17 @@
     "node": true
   },
   "plugins": ["jsdoc"],
-  "extends": ["eslint:recommended", "prettier"],
+  "extends": ["eslint:recommended", "plugin:jsdoc/recommended", "prettier"],
   "globals": { "Set": true, "Symbol": true },
   "rules": {
-    "no-eq-null": 0,
     "no-proto": 2,
     "curly": [2, "multi-line"],
     "one-var": [2, "never"],
     "no-else-return": 2,
     "no-shadow": 2,
     "no-use-before-define": [2, "nofunc"],
 
+    "jsdoc/require-jsdoc": 0,
     "jsdoc/check-param-names": 2,
     "jsdoc/check-tag-names": 2,
     "jsdoc/check-types": 2,
@@ -30,6 +30,10 @@
     "jsdoc": {
       "additionalTagNames": {
         "customTags": ["hideconstructor"]
+      },
+      "preferredTypes": {
+        "node": "Node",
+        "cheerio": "Cheerio"
       }
     }
   }

index.js

@@ -22,56 +22,56 @@ exports.text = staticMethods.text;
 exports.xml = staticMethods.xml;
 
 /**
- * In order to promote consistency with the jQuery library, users are
- * encouraged to instead use the static method of the same name.
+ * In order to promote consistency with the jQuery library, users are encouraged
+ * to instead use the static method of the same name.
  *
+ * @deprecated
  * @example
- *     var $ = cheerio.load('<div><p></p></div>');
- *     $.contains($('div').get(0), $('p').get(0)); // true
- *     $.contains($('p').get(0), $('div').get(0)); // false
+ *   var $ = cheerio.load('<div><p></p></div>');
+ *   $.contains($('div').get(0), $('p').get(0)); // true
+ *   $.contains($('p').get(0), $('div').get(0)); // false
  *
  * @function
  * @returns {boolean}
- * @deprecated
  */
 exports.contains = staticMethods.contains;
 
 /**
- * In order to promote consistency with the jQuery library, users are
- * encouraged to instead use the static method of the same name.
+ * In order to promote consistency with the jQuery library, users are encouraged
+ * to instead use the static method of the same name.
  *
+ * @deprecated
  * @example
- *     var $ = cheerio.load('');
- *     $.merge([1, 2], [3, 4]) // [1, 2, 3, 4]
+ *   var $ = cheerio.load('');
+ *   $.merge([1, 2], [3, 4]); // [1, 2, 3, 4]
  *
  * @function
- * @deprecated
  */
 exports.merge = staticMethods.merge;
 
 /**
- * In order to promote consistency with the jQuery library, users are
- * encouraged to instead use the static method of the same name as it is
- * defined on the "loaded" Cheerio factory function.
+ * In order to promote consistency with the jQuery library, users are encouraged
+ * to instead use the static method of the same name as it is defined on the
+ * "loaded" Cheerio factory function.
  *
+ * @deprecated See {@link static/parseHTML}.
  * @example
- *     var $ = cheerio.load('');
- *     $.parseHTML('<b>markup</b>');
+ *   var $ = cheerio.load('');
+ *   $.parseHTML('<b>markup</b>');
  *
  * @function
- * @deprecated See {@link static/parseHTML}.
  */
 exports.parseHTML = staticMethods.parseHTML;
 
 /**
  * Users seeking to access the top-level element of a parsed document should
  * instead use the `root` static method of a "loaded" Cheerio function.
  *
+ * @deprecated
  * @example
- *     var $ = cheerio.load('');
- *     $.root();
+ *   var $ = cheerio.load('');
+ *   $.root();
  *
  * @function
- * @deprecated
  */
 exports.root = staticMethods.root;