diff --git a/lib/values-builder.js b/lib/values-builder.js
index 55cda264..19e719df 100644
--- a/lib/values-builder.js
+++ b/lib/values-builder.js
@@ -307,19 +307,27 @@ function udf() {
 
 /**
  * Sets the slice clause of a built query to select the slice
- * of the result set based on the first tuple and the number
- * of tuples (aka rows).
+ * of the result set based on the start tuple within the result set
+ * and the number of tuples (aka rows) in the slice.
  * This function must be called on the builtQuery returned
  * by the {@link valuesBuilder#valuesFromIndexes} function
  * or another function specifying a values query clause.
+ * By default, the slice uses array slice mode, but you can switch
+ * to legacy slice mode with {@link marklogic.setSliceMode}. Legacy
+ * slice mode is deprecated and will be removed in the next major release.
  * @method valuesBuilder.BuiltQuery#slice
  * @since 1.0
- * @param {number} start - the one-based position within the
- * result set of the first tuple.
- * @param {number} length - the number of tuples in the slice.
+ * @param {number} start - in array slice mode, the zero-based position
+ * within the result set of the first tuple; in legacy slice mode, the
+ * one-based position within the result set of the first tuple or 0 to
+ * suppress the tuples and return only the summary
+ * @param {number} length - in array slice mode, the zero-based position
+ * of the tuple after the last document in the slice or 0 to suppress
+ * the documents and return only the summary; in legacy slice mode, the
+ * number of tuples in the slice
  * @param {transform} [transform] - a transform to apply to the
  * slice on the server as specified by the {@link valuesBuilder#transform}
- * function.
+ * function
  * @returns {valuesBuilder.BuiltQuery} a built query
  */
 ValueBuilder.prototype.slice = function valuesSlice() {