docs(query): updated explanation for slice

fix Automattic#12474

lib/query.js

@@ -370,17 +370,33 @@ Query.prototype.clone = function clone() {
  *
  * #### Example:
  *
- *     query.slice('comments', 5);
- *     query.slice('comments', -5);
- *     query.slice('comments', [10, 5]);
- *     query.where('comments').slice(5);
- *     query.where('comments').slice([-10, 5]);
+ *     query.slice('comments', 5); // Returns the first 5 comments
+ *     query.slice('comments', -5); // Returns the last 5 comments
+ *     query.slice('comments', [10, 5]); // Returns the first 5 comments after the 10-th
+ *     query.where('comments').slice(5); // Returns the first 5 comments
+ *     query.where('comments').slice([-10, 5]); // Returns the first 5 comments after the 10-th to last
+ *
+ * **Note:** If the absolute value of the number of elements to be sliced is greater than the number of elements in the array, all array elements will be returned.
+ *
+ *      // Given `arr`: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+ *      query.slice('arr', 20); // Returns [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+ *      query.slice('arr', -20); // Returns [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+ *
+ * **Note:** If the number of elements to skip is positive and greater than the number of elements in the array, an empty array will be returned.
+ *
+ *      // Given `arr`: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+ *      query.slice('arr', [20, 5]); // Returns []
+ *
+ * **Note:** If the number of elements to skip is negative and its absolute value is greater than the number of elements in the array, the starting position is the start of the array.
+ *
+ *      // Given `arr`: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+ *      query.slice('arr', [-20, 5]); // Returns [1, 2, 3, 4, 5]
  *
  * @method slice
  * @memberOf Query
  * @instance
  * @param {String} [path]
- * @param {Number} val number/range of elements to slice
+ * @param {Number|Array} val number of elements to slice or array with number of elements to skip and number of elements to slice
  * @return {Query} this
  * @see mongodb https://www.mongodb.org/display/DOCS/Retrieving+a+Subset+of+Fields#RetrievingaSubsetofFields-RetrievingaSubrangeofArrayElements
  * @see $slice https://docs.mongodb.org/manual/reference/projection/slice/#prj._S_slice