Document QueryBuilder composition in .where()

[jmakeig]

.where() will accept zero or one parsed queries and will AND those with with zero or more built queries. However, when using a query-by-example, that must be the only query.

(Can you also please add a "Documentation" issue label?)

[ehennum]

I presume, Justin, you meant to asign this to Kim. I'll ask our GitHub admins for a documentation issue label.

[jmakeig]

Who owns the jsDoc? I would presume we’d start with the API doc of the input params.

[ehennum]

The JSDoc for .where() already says the same thing in a different way:

Sets the where clause of a built query, using the helper functions of a queryBuilder to specify either a single query by example, a structured query, a string query, or both structured and string queries. You can use an empty where clause to qualify all documents in the database (though for large databases, you would not want to retrieve all documents in a single request).

[kcoleman-marklogic]

The book also says you can combine string and structured query together but that QBE can only be used alone.

[kcoleman-marklogic]

Is there action actually required on this issue? Erik says the JSDoc already says this. I think the guide does, too.

[jmakeig]

The only thing I'd add is an explanation of the default AND behavior when combining queries. Some examples of the permutations in the jsDoc would be helpful to illustrate too.

[kcoleman-marklogic]

Erik, here's my whack at clarifying the jsdoc for where(). If you prefer me to integrate it or go through all the pull request gyrations, reassign back to me. I also added an example to the book that shows passing multiple queries to where(), including a combination of string and structured.

New jsdoc for where() in lib/query-builder.js:

/**
 * Sets the where clause of a built query, using the helper functions
 * of a {@link queryBuilder} to specify either a single query by example,
 * a structured query, a string query, or both structured and string queries.
 * When you include a string and structured query, they are AND'd together.
 * You can use an empty where clause to qualify all documents in the database
 * (though for large databases, you would not want to retrieve all documents
 * in a single request).
 * This function may be called on a query builder or on the result of building a query.
 * @method
 * @memberof queryBuilder#
 * @param {queryBuilder.Query|queryBuilder.ParsedQuery|queryBuilder.QueryByExample} [query] - one
 * or more composable queries returned by query builder functions; or 
 * a parsed query returned by the {@link queryBuilder#parsedFrom} function; or
 * or a parsed query plus one or more composable queries, which are implicitly
 * AND'd together; or a query by example returned by the 
 * {@link queryBuilder#byExample} function.
 */

As a diff so you can see what I actually did:

diff --git a/lib/query-builder.js b/lib/query-builder.js
index 4e35a80..064ee58 100644
--- a/lib/query-builder.js
+++ b/lib/query-builder.js
@@ -3283,17 +3283,19 @@ function copyFromQueryBuilder(otherQueryBuilder) {
  * Sets the where clause of a built query, using the helper functions
  * of a {@link queryBuilder} to specify either a single query by example,
  * a structured query, a string query, or both structured and string queries.
+ * When you include a string and structured query, they are AND'd together.
  * You can use an empty where clause to qualify all documents in the database
  * (though for large databases, you would not want to retrieve all documents
  * in a single request).
  * This function may be called on a query builder or on the result of building a query.
  * @method
  * @memberof queryBuilder#
- * @param {queryBuilder.Query|queryBuilder.ParsedQuery|queryBuilder.QueryByExample} [query] - either
- * one or more composable queries returned by query builder functions,
- * a parsed query returned by the {@link queryBuilder#parsedFrom} function, or
- * a query by example returned by the {@link queryBuilder#byExample} function.
- * @returns {queryBuilder.BuiltQuery} a built query
+ * @param {queryBuilder.Query|queryBuilder.ParsedQuery|queryBuilder.QueryByExample} [query] - one
+ * or more composable queries returned by query builder functions; or
+ * a parsed query returned by the {@link queryBuilder#parsedFrom} function; or
+ * or a parsed query plus one or more composable queries, which are implicitly
+ * AND'd together; or a query by example returned by the
+ * {@link queryBuilder#byExample} function.
  */
 function where() {
   var self = (this instanceof QueryBuilder) ? this : new QueryBuilder();