From 2585055f48fb4a40fb87daccf7a217c8f4ff45de Mon Sep 17 00:00:00 2001
From: Anne Ogborn <annie66us@yahoo.com>
Date: Fri, 21 Feb 2020 18:44:09 +0100
Subject: [PATCH] Improve documentation for boolean operations

---
 lib/woql.js | 34 +++++++++++++++++++++++++++++++---
 1 file changed, 31 insertions(+), 3 deletions(-)

diff --git a/lib/woql.js b/lib/woql.js
index b0d7e354..f5202ddb 100644
--- a/lib/woql.js
+++ b/lib/woql.js
@@ -69,21 +69,49 @@ WOQL.start = function(start, query){ return new WOQLQuery().start(start, query);
 WOQL.select = function(...list){ return new WOQLQuery().select(...list); }
 
 /**
- * Creates a logical OR of the arguments
+ * Filter the query so only those triples that match any of the subqueries are included
  * @param queries - WOQL Query objects
  * @return {object} WOQLQuery
+ *
+ *
+ * @example
+ * // find triples that are of type scm:Journey, and have
+ * // a start_station v:Start, and that start_station is labeled
+ * // v:Start_Label
+ *
+ * WOQL.and(
+ *      WOQL.triple("v:Journey", "type", "scm:Journey"),
+ *      WOQL.or(
+ *          WOQL.triple("v:Journey", "scm:start_station", "doc:Station31007"),
+ *          WOQL.triple("v:Journey", "scm:start_station", "doc:Station31114")),
+ *      WOQL.triple("v:Journey", "scm:start_station", "v:Start"),
+ *      WOQL.triple("v:Start", "label", "v:Start_Label"))
+ *
+ * @see WOQLQuery().woql_or for WOQL.py version of the same function
  */
 WOQL.or = function(...queries){	return new WOQLQuery().or(...queries); }
 
 /**
- * Creates a logical AND of the arguments
+ * Filter the query so only those triples that match all of the subqueries are included
  * @param queries - WOQL Query objects
  * @return {object} WOQLQuery
+ *
+ * @example
+ * // find triples that are of type scm:Journey, and have
+ * // a start_station v:Start, and that start_station is labeled
+ * // v:Start_Label
+ *
+ * WOQL.and(
+ *      WOQL.triple("v:Journey", "type", "scm:Journey"),
+ *      WOQL.triple("v:Journey", "start_station", "v:Start"),
+ *      WOQL.triple("v:Start", "label", "v:Start_Label"))
+ *
+ * @see WOQLQuery().woql_and for WOQL.py version of the same function
  */
 WOQL.and = function(...queries){ return new WOQLQuery().and(...queries); }
 
 /**
- * Creates a logical NOT of the arguments
+ * Include only triples that do not match the single contained query
  * @param queries - WOQL Query objects
  * @return {object} WOQLQuery
  */