Fix: Predicate args in documentation

README.org

@@ -88,8 +88,9 @@ Arguments are listed next to predicate names, when applicable.
 Note that, for convenience, standard numeric comparator function symbols (~<~, ~=~, etc.) do not need to be quoted when passed as an argument to these predicates.  The resemblance to infix notation is coincidental.  See examples in documentation.
 
 +  ~category (&optional categories)~ :: Return non-nil if current heading is in one or more of ~CATEGORIES~ (a list of strings).
++  ~clocked (&key from to on)~ :: Return non-nil if current entry was clocked in given period.  If no arguments are specified, return non-nil if entry was clocked at any time.  If ~FROM~, return non-nil if entry was clocked on or after ~FROM~.  If ~TO~, return non-nil if entry was clocked on or before ~TO~.  If ~ON~, return non-nil if entry was clocked on date ~ON~.  ~FROM~, ~TO~, and ~ON~ should be strings parseable by ~parse-time-string~ but may omit the time value.  Note: See macrolet in ~org-ql-query~ which pre-processes arguments to this function, parsing timestamp strings into Unix timestamps and accepting `:on' keyword.
 +  ~closed (&optional comparator target-date)~ :: Return non-nil if entry's closed date compares with ~TARGET-DATE~ using ~COMPARATOR~.  ~TARGET-DATE~ should be a string parseable by ~date-to-day~.  ~COMPARATOR~ should be a function (like ~<=~).
-+  ~date (&optional comparator target-date &optional)~ :: Return non-nil if Org entry at point has date of ~TYPE~ that compares with ~TARGET-DATE~ using ~COMPARATOR~.  Checks all Org-formatted timestamp strings in entry.  ~TYPE~ may be ~active~, ~inactive~, or ~all~, to control whether active, inactive, or all timestamps are checked.  Ranges of each type are also checked.  ~TARGET-DATE~ should be a string parseable by ~date-to-day~.  ~COMPARATOR~ should be a function (like ~<=~).
++  ~date (&optional comparator target-date type)~ :: Return non-nil if Org entry at point has date of ~TYPE~ that compares with ~TARGET-DATE~ using ~COMPARATOR~.  Checks all Org-formatted timestamp strings in entry.  ~TYPE~ may be ~active~, ~inactive~, or ~all~, to control whether active, inactive, or all timestamps are checked.  Ranges of each type are also checked.  ~TARGET-DATE~ should be a string parseable by ~date-to-day~.  ~COMPARATOR~ should be a function (like ~<=~).
 +  ~deadline (&optional comparator target-date)~ :: Return non-nil if entry's deadline compares with ~TARGET-DATE~ using ~COMPARATOR~.  ~TARGET-DATE~ should be a string parseable by ~date-to-day~.  ~COMPARATOR~ should be a function (like ~<=~).
 +  ~done~ :: Return non-nil if entry's ~TODO~ keyword is in ~org-done-keywords~.
 +  ~habit~ :: Return non-nil if entry is a habit.
@@ -103,6 +104,7 @@ Note that, for convenience, standard numeric comparator function symbols (~<~, ~
 +  ~tags (&optional tags)~ :: Return non-nil if current heading has one or more of ~TAGS~ (a list of strings).
 +  ~todo (&optional keywords)~ :: Return non-nil if current heading is a ~TODO~ item.  With ~KEYWORDS~, return non-nil if its keyword is one of ~KEYWORDS~ (a list of strings).
 
+
 ** Functions / Macros
 :PROPERTIES:
 :TOC:      ignore-children
@@ -276,11 +278,10 @@ Generates the predicate subtree.
             (s-join "\n" (->> org-ql-predicates
                               (--sort (string< (symbol-name (plist-get it :name))
                                                (symbol-name (plist-get other :name))))
-                              (--map (-let* (((&plist :name name :docstring docstring :fn fn) it)
+                              (--map (-let* (((&plist :name name :docstring docstring :fn fn :args args) it)
-                                             (args (->> (help-function-arglist fn)
+                                             (args (->> args
-                                                        (--replace-where (eq it '&rest) '&optional)
+                                                        (--replace-where (listp it) (car it))
-                                                        ;; Comparing the `--cl-rest--' symbol itself doesn't work for some reason.
+                                                        (--replace-where (eq '&rest it) '&optional))))
-                                                        (--remove (string= (symbol-name it) "--cl-rest--")))))
                                        (if docstring
                                            (progn
                                              (setq docstring (s-replace "\n" "  " docstring))

org-ql.el

@@ -51,7 +51,7 @@ This list should not contain any duplicates.")
   (let ((fn-name (intern (concat "org-ql--predicate-" (symbol-name name))))
         (pred-name (intern (symbol-name name))))
     `(progn
-       (push (list :name ',pred-name :fn ',fn-name :docstring ,docstring) org-ql-predicates)
+       (push (list :name ',pred-name :fn ',fn-name :docstring ,docstring :args ',args) org-ql-predicates)
        (cl-defun ,fn-name ,args ,docstring ,@body))))
 
 (cl-defmacro org-ql (buffers-or-files query &key sort narrow markers
@@ -298,7 +298,7 @@ empty time values to 23:59:59; otherwise, to 00:00:00."
 
 ;;;;; Predicates
 
-(org-ql--defpredicate clocked (&key from to)
+(org-ql--defpredicate clocked (&key from to on)
   "Return non-nil if current entry was clocked in given period.
 If no arguments are specified, return non-nil if entry was
 clocked at any time.
@@ -315,7 +315,6 @@ arguments to this function, parsing timestamp strings into Unix
 timestamps and accepting `:on' keyword."
   ;; NOTE: FROM and TO are actually expected to be Unix timestamps.  The docstring is written
   ;; for end users, for which the arguments are pre-processed by `org-ql-query'.
-  (declare (advertised-calling-convention (&key from to on) nil))
   ;; FIXME: This assumes every "clocked" entry is a range.  Unclosed clock entries are not handled.
   (cl-macrolet ((next-timestamp ()
                                 `(when (re-search-forward org-clock-line-re end-pos t)