Merge pull request #369 from wooldridge/issues/withopts-227

fix(#227): clarify when a summary object appears in query results

Author: wooldridge

lib/documents.js

@@ -172,7 +172,7 @@ function wipeOutputTransform(/*headers, data*/) {
 /**
  * Categories of information to read or write for documents.
  * The possible values of the enumeration are
- * content|collections|permissions|properties|quality|metadataValues|metadata where
+ * content|collections|metadataValues|permissions|properties|quality|metadata|none where
  * metadata is an alias for all of the categories other than content.
  * @typedef {enum} documents.categories
  * @since 1.0

lib/query-builder.js

@@ -5097,7 +5097,10 @@ function snippet() {
 /**
  * Sets the withOptions clause of a built query to configure the query;
  * takes a configuration object with the following named parameters.
- * This function may be called on the result of building a query.
+ * This function may be called on the result of building a query. When the
+ * 'debug', 'metrics', 'queryPlan', or 'similarDocs' parameter is set, a
+ * search summary object will be returned along with the result documents.
+ * When 'categories' is set to 'none', only a search summary is returned.
  * @method
  * @since 1.0
  * @memberof queryBuilder#
@@ -5106,7 +5109,8 @@ function snippet() {
  * @param {number} [concurrencyLevel] - the maximum number of threads to use to calculate facets
  * @param {string|string[]} [forestNames] - the ids of forests providing documents
  * for the result set
- * @param {...string} [search] - options modifying the default behaviour of the query
+ * @param {...string} [search] - <a href="https://docs.marklogic.com/guide/search-dev/appendixa#id_77801">options</a>
+ * modifying the default behaviour of the query
  * @param {string|transactions.Transaction}  [txid] - a string
  * transaction id or Transaction object identifying an open
  * multi-statement transaction