Tidy: Docstrings

org-ql-search.el

@@ -50,7 +50,7 @@
 ;;;; Variables
 
 (defvar org-ql-block-header nil
-  "An optional string to override the default header in `org-ql-block' agenda blocks.")
+  "Optional string overriding default header in `org-ql-block' agenda blocks.")
 
 ;;;; Customization
 
@@ -277,13 +277,16 @@ Valid parameters include:
   :ts-format  Optional format string used to format
               timestamp-based columns.
 
-For example, an org-ql dynamic block header could look like:
+For example, an org-ql dynamic block header could look like
+this (must be a single line in the Org buffer):
 
-  #+BEGIN: org-ql :query (todo \"UNDERWAY\") :columns (priority todo heading) :sort (priority date) :ts-format \"%Y-%m-%d %H:%M\""
+  #+BEGIN: org-ql :query (todo \"UNDERWAY\")
+:columns (priority todo heading) :sort (priority date)
+:ts-format \"%Y-%m-%d %H:%M\""
   (-let* (((&plist :query :columns :sort :ts-format :take) params)
           (query (cl-etypecase query
                    (string (org-ql--query-string-to-sexp query))
-                   (list  ;; SAFETY: Query is in sexp form: ask for confirmation, because it could contain arbitrary code.
+                   (list ;; SAFETY: Query is in sexp form: ask for confirmation, because it could contain arbitrary code.
                     (org-ql--ask-unsafe-query query)
                     query)))
           (columns (or columns '(heading todo (priority "P"))))
@@ -337,7 +340,7 @@ For example, an org-ql dynamic block header could look like:
                                        columns)
                                 " | ")
               " |" "\n")
-      (insert "|- \n")  ; Separator hline
+      (insert "|- \n")                  ; Separator hline
       (dolist (element elements)
         (insert "| " (format-element element) " |" "\n"))
       (delete-char -1)
@@ -345,13 +348,19 @@ For example, an org-ql dynamic block header could look like:
 
 ;;;; Functions
 
+(defvar org-ql-search-directories-files-error
+  ;; Workaround to silence byte-compiler which thinks having this string in an
+  ;; argument's default value form is a too-long docstring.
+  "No DIRECTORIES given, and `org-directory' doesn't exist")
+
 (cl-defun org-ql-search-directories-files
-    (&key (directories (if (file-exists-p org-directory)
+    (&key (directories
-                           (list org-directory)
+           (if (file-exists-p org-directory)
-                         (user-error "Org-ql-search-directories-files: No DIRECTORIES given, and `org-directory' doesn't exist")))
+               (list org-directory)
+             (user-error org-ql-search-directories-files-error)))
           (recurse org-ql-search-directories-files-recursive)
           (regexp org-ql-search-directories-files-regexp))
-  "Return list of matching files in DIRECTORIES, a list of directory paths.
+  "Return list of matching files in DIRECTORIES.
 When RECURSE is non-nil, recurse into subdirectories.  When
 REGEXP is non-nil, only return files that match REGEXP."
   (let ((files (->> directories

org-ql.el

@@ -229,7 +229,8 @@ regexps.")
                                    (group-n 1 (regexp ,org-ql-regexp-ts-inactive)))
                               (seq (or "DEADLINE" "SCHEDULED") ":" (0+ " ")
                                    (group-n 1 (regexp ,org-ql-regexp-ts-active))))))
-  "Matches CLOSED, DEADLINE or SCHEDULED keyword with timestamp, with or without time.")
+  "Matches CLOSED, DEADLINE or SCHEDULED keyword with timestamp.
+Matches with or without time.")
 
 (defvar org-ql-regexp-planning-with-time
   (rx-to-string `(seq bow (or (seq "CLOSED" ":" (0+ " ")
@@ -503,8 +504,14 @@ NARROW corresponds to the `org-ql-select' argument NARROW."
 
 (cl-defun org-ql--select (&key preamble preamble-case-fold predicate action narrow
                                &allow-other-keys)
-  "Return results of mapping function ACTION across entries in current buffer matching function PREDICATE.
+  "Return results for given arguments.
-If NARROW is non-nil, buffer will not be widened."
+Return results of mapping function ACTION across entries in
+current buffer matching function PREDICATE.  If NARROW is
+non-nil, buffer will not be widened.
+
+PREAMBLE may be a regexp to search for before calling PREDICATE.
+When doing so, `case-fold-search' is bound to
+PREAMBLE-CASE-FOLD."
   ;; Since the mappings are stored in the variable `org-ql-predicates', macros like `flet'
   ;; can't be used, so we do it manually (this is same as the equivalent `flet' expansion).
   ;; Mappings are stored in the variable because it allows predicates to be defined with a
@@ -1327,7 +1334,7 @@ result form."
 (setf org-ql-defpred-defer t)
 
 (org-ql-defpred (category c) (&rest categories)
-  "Return non-nil if current heading is in one or more of CATEGORIES (a list of strings)."
+  "Return non-nil if current heading is in one or more of CATEGORIES."
   :normalizers ((`(,predicate-names . ,rest)
                  `(category ,@rest)))
   :body (when-let ((category (org-get-category (point))))
@@ -1359,7 +1366,8 @@ The following forms are accepted:
 
   (effort DURATION): Matches if effort is DURATION.
   (effort DURATION DURATION): Matches if effort is between DURATIONs, inclusive.
-  (effort COMPARATOR DURATION): Matches if effort compares to DURATION with COMPARATOR.
+  (effort COMPARATOR DURATION): Matches if effort compares to DURATION with
+                                COMPARATOR.
 
 COMPARATOR may be `<', `<=', `>', or `>='.  DURATION should be an
 Org effort string, like \"5\" or \"0:05\"."
@@ -1492,8 +1500,10 @@ Matching is done case-insensitively."
 The following forms are accepted:
 
   (level NUMBER): Matches if heading level is NUMBER.
-  (level NUMBER NUMBER): Matches if heading level is equal to or between NUMBERs.
+  (level NUMBER NUMBER): Matches if heading level is equal to or between
-  (level COMPARATOR NUMBER): Matches if heading level compares to NUMBER with COMPARATOR.
+                         NUMBERs.
+  (level COMPARATOR NUMBER): Matches if heading level compares to NUMBER with
+                             COMPARATOR.
 
 COMPARATOR may be `<', `<=', `>', or `>='."
   :normalizers ((`(,predicate-names . ,args)
@@ -1610,7 +1620,7 @@ any link is found."
                                        (match-string org-ql-link-description-group)))))))))
 
 (org-ql-defpred (rifle smart) (&rest strings)
-  "Return non-nil if each string argument is found in either the entry or its outline path.
+  "Return non-nil if each of strings is found in the entry or its outline path.
 Works like `org-rifle'.  This is probably the most useful,
 intuitive, general-purpose predicate."
   ;; NOTE: This predicate advertises that it takes strings, but they
@@ -1677,7 +1687,7 @@ contiguous segment of the outline path:
   :body (org-ql--infix-p regexps (org-ql--value-at (point) #'org-ql--outline-path)))
 
 (org-ql-defpred path (&rest regexps)
-  "Return non-nil if current heading's buffer's filename path matches any of REGEXPS (regexp strings).
+  "Return non-nil if current heading's buffer's file path matches any of REGEXPS.
 Without arguments, return non-nil if buffer is file-backed."
   ;; FIXME: This should AND the regexps together, not OR them.
   :body (when (buffer-file-name)
@@ -1764,7 +1774,7 @@ priority B)."
                 thereis (= item-priority (* 1000 (- org-lowest-priority (string-to-char priority-arg)))))))))
 
 (org-ql-defpred property (property &optional value &key inherit)
-  "Return non-nil if current entry has PROPERTY (a string), and optionally VALUE (a string).
+  "Return non-nil if current entry has PROPERTY, and optionally VALUE.
 If INHERIT is nil, only match entries with PROPERTY set on the
 entry; if t, also match entries with inheritance.  If INHERIT is
 not specified, use the Boolean value of
@@ -1856,7 +1866,7 @@ interpreted as nil or non-nil)."
                         (re-search-forward regexp end t))))))
 
 (org-ql-defpred src (&key regexps lang)
-  "Return non-nil if current entry contains an Org source block matching all of REGEXPS.
+  "Return non-nil if current entry has an Org source block matching all REGEXPS.
 If keyword argument LANG is non-nil, the block must be in that
 language.  Matching is done case-insensitively."
   :coalesce (lambda (coalesced-args current-args)
@@ -1968,7 +1978,7 @@ Tests both inherited and local tags."
   :body (apply #'org-ql--predicate-tags tags))
 
 (org-ql-defpred (tags-inherited inherited-tags tags-i itags) (&rest tags)
-  "Return non-nil if current heading's inherited tags include one or more of TAGS (a list of strings).
+  "Return non-nil if current heading's inherited tags include any of TAGS.
 If TAGS is nil, return non-nil if heading has any inherited tags."
   :normalizers ((`(,predicate-names . ,tags)
                  `(tags-inherited ,@tags)))
@@ -1982,7 +1992,7 @@ If TAGS is nil, return non-nil if heading has any inherited tags."
                            (seq-intersection tags inherited)))))))
 
 (org-ql-defpred (tags-local local-tags tags-l ltags) (&rest tags)
-  "Return non-nil if current heading's local tags include one or more of TAGS (a list of strings).
+  "Return non-nil if current heading's local tags include any of TAGS.
 If TAGS is nil, return non-nil if heading has any local tags."
   :normalizers ((`(,predicate-names . ,tags)
                  `(tags-local ,@tags)))
@@ -2025,7 +2035,7 @@ Tests both inherited and local tags."
 
 (org-ql-defpred todo (&rest 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)."
+With KEYWORDS, return non-nil if its keyword is one of KEYWORDS."
   ;; TODO: Can we make a preamble for plain (todo) queries?
   :preambles ((`(,predicate-names . ,(and todo-keywords (guard todo-keywords)))
                (list :case-fold nil :regexp (rx-to-string `(seq bol (1+ "*") (1+ space) (or ,@todo-keywords) (or " " eol)) t))))
@@ -2239,7 +2249,8 @@ non-nil if entry has a deadline."
 (org-ql-defpred deadline-warning (&key from to)
   ;; TODO: Should this also accept a WITH-TIME argument?
   ;; MAYBE: Use the new org-ql-regexps?
-  "Internal predicate used to handle `org-deadline-warning-days' and deadlines with warning periods."
+  "Internal predicate.
+Used to handle `org-deadline-warning-days' and deadlines with warning periods."
   :preambles ((`(,predicate-names . ,_)
                (list :regexp org-deadline-time-regexp :query query)))
   :body