From 4d186d705449d94fa21de0c6433a28a65f0268ba Mon Sep 17 00:00:00 2001
From: Adam Porter <adam@alphapapa.net>
Date: Sat, 8 Jun 2019 04:24:50 -0500
Subject: [PATCH] Docs: org-ql, org-ql-query

Also rename org-ql--query to org-ql-query.
---
 README.org | 30 ++++++++++++++++++++++++++++++
 org-ql.el  |  6 +++---
 2 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/README.org b/README.org
index 1694f08..b1903da 100644
--- a/README.org
+++ b/README.org
@@ -107,6 +107,36 @@ Here are some other examples:
              (closed = today))))
 #+END_SRC
 
+** Functions / Macros
+
+*** Macro: ~org-ql~
+
+/Arguments:/ ~(buffers-or-files pred-body &key sort narrow markers action)~
+
+Find entries in ~BUFFERS-OR-FILES~ that match ~PRED-BODY~, and return the results of running ~ACTION-FN~ on each matching entry.
+
+~ACTION~ is a sexp which will be evaluated at each matching entry with point at the beginning of its heading.  It is passed to ~org-ql--query~ as a lambda.  By default, ~org-element-headline-parser~ is called to return an Org element.
+
+~SORT~ is a user defined sorting function, or an unquoted list of one or more sorting methods, including: ~date~, ~deadline~, ~scheduled~, ~todo~, and ~priority~.
+
+If ~NARROW~ is non-nil, query will run without widening the buffer (the default is to widen and search the entire buffer).
+
+If ~MARKERS~ is non-nil, ~org-agenda-ng--add-markers~ is used to add markers to each item, pointing to the item in its source buffer.  In this case, ~ACTION~ should return an Org element.
+
+*** Function: ~org-ql-query~
+
+/Arguments:/ ~(buffers-or-files query &key action narrow sort)~
+
+Return items matching ~QUERY~ in ~BUFFERS-OR-FILES~.
+
+~QUERY~ is an ~org-ql~ query sexp.
+
+~ACTION~ is a function which is called on each matching entry, with point at the beginning of its heading.  For example, ~org-element-headline-parser~ may be used to parse an entry into an Org element (note that it must be called with a limit argument, so a lambda must be used to do so).  Also see ~org-ql--add-markers~, which may be used to add markers compatible with Org Agenda code.
+
+If ~NARROW~ is non-nil, buffers are not widened.
+
+~SORT~ is either nil, in which case items are not sorted; or one or a list of defined ~org-ql~ sorting methods: ~date~, ~deadline~, ~scheduled~, ~todo~, and ~priority~.
+
 ** Predicates
 
 Arguments are listed next to predicate names, when applicable.
diff --git a/org-ql.el b/org-ql.el
index bf1be9b..06c8438 100644
--- a/org-ql.el
+++ b/org-ql.el
@@ -58,7 +58,7 @@ This list should not contain any duplicates.")
 
 ACTION is a sexp which will be evaluated at each matching entry
 with point at the beginning of its heading.  It is passed to
-`org-ql--query' as a lambda.  By default, `org-element-headline-parser'
+`org-ql-query' as a lambda.  By default, `org-element-headline-parser'
  is called to return an Org element.
 
 SORT is a user defined sorting function, or an unquoted list of
@@ -81,7 +81,7 @@ buffer.  In this case, ACTION should return an Org element."
                        ;; maybe this should be on the agenda-ng side.
                        (->> ,action
                             org-ql--add-markers)))))
-  `(org-ql--query ,buffers-or-files
+  `(org-ql-query ,buffers-or-files
      ',pred-body
      :action ,action
      :narrow ,narrow
@@ -98,7 +98,7 @@ buffer.  In this case, ACTION should return an Org element."
 
 ;;;; Functions
 
-(cl-defun org-ql--query (buffers-or-files query &key action narrow sort)
+(cl-defun org-ql-query (buffers-or-files query &key action narrow sort)
   "Return items matching QUERY in BUFFERS-OR-FILES.
 
 QUERY is an `org-ql' query sexp.