refactor: Document after, before, slice arguments, improve handling (#…

…1721)

Co-authored-by: Felix Böhm <me@feedic.com>

lib/api/manipulation.js

@@ -484,6 +484,8 @@ exports.wrapAll = function (wrapper) {
   return this;
 };
 
+/*eslint-disable jsdoc/check-param-names*/
+
 /**
  * Insert content next to each element in the set of matched elements.
  *
@@ -497,6 +499,9 @@ exports.wrapAll = function (wrapper) {
  *   //      <li class="pear">Pear</li>
  *   //    </ul>
  *
+ * @param {...(string | Element | Element[] | Cheerio | Function)} content -
+ *   HTML string, DOM element, array of DOM elements or Cheerio to insert after
+ *   each element in the set of matched elements.
  * @see {@link https://api.jquery.com/after/}
  *
  * @returns {Cheerio} The instance itself.
@@ -529,6 +534,8 @@ exports.after = function () {
   });
 };
 
+/*eslint-enable jsdoc/check-param-names*/
+
 /**
  * Insert every element in the set of matched elements after the target.
  *
@@ -580,6 +587,8 @@ exports.insertAfter = function (target) {
   return this.constructor.call(this.constructor, this._makeDomArray(clones));
 };
 
+/*eslint-disable jsdoc/check-param-names*/
+
 /**
  * Insert content previous to each element in the set of matched elements.
  *
@@ -593,6 +602,9 @@ exports.insertAfter = function (target) {
  *   //      <li class="pear">Pear</li>
  *   //    </ul>
  *
+ * @param {...(string | Element | Element[] | Cheerio | Function)} content -
+ *   HTML string, DOM element, array of DOM elements or Cheerio to insert
+ *   before each element in the set of matched elements.
  * @see {@link https://api.jquery.com/before/}
  *
  * @returns {Cheerio} The instance itself.
@@ -625,6 +637,8 @@ exports.before = function () {
   });
 };
 
+/*eslint-enable jsdoc/check-param-names*/
+
 /**
  * Insert every element in the set of matched elements before the target.
  *

lib/api/traversing.js

@@ -10,6 +10,7 @@ var utils = require('../utils');
 var domEach = utils.domEach;
 var uniqueSort = require('htmlparser2').DomUtils.uniqueSort;
 var isTag = utils.isTag;
+var slice = Array.prototype.slice;
 var reSiblingSelector = /^\s*[~+]/;
 
 /**
@@ -801,7 +802,7 @@ exports.eq = function (i) {
  */
 exports.get = function (i) {
   if (i == null) {
-    return Array.prototype.slice.call(this);
+    return slice.call(this);
   }
   return this[i < 0 ? this.length + i : i];
 };
@@ -841,7 +842,7 @@ exports.index = function (selectorOrNeedle) {
 };
 
 /**
- * Gets the elements matching the specified range.
+ * Gets the elements matching the specified range (0-based position).
  *
  * @example
  *   $('li').slice(1).eq(0).text();
@@ -850,12 +851,17 @@ exports.index = function (selectorOrNeedle) {
  *   $('li').slice(1, 2).length;
  *   //=> 1
  *
+ * @param {number} [start] - An position at which the elements begin to be
+ *   selected. If negative, it indicates an offset from the end of the set.
+ * @param {number} [end] - An position at which the elements stop being
+ *   selected. If negative, it indicates an offset from the end of the set. If
+ *   omitted, the range continues until the end of the set.
  * @see {@link https://api.jquery.com/slice/}
  *
  * @returns {Cheerio} The elements matching the specified range.
  */
-exports.slice = function () {
-  return this._make([].slice.apply(this, arguments));
+exports.slice = function (start, end) {
+  return this._make(slice.call(this, start, end));
 };
 
 function traverseParents(self, elem, selector, limit) {