From d86a402ba5bf549ea5100c11aec2df32cd91d50c Mon Sep 17 00:00:00 2001 From: Adam Porter Date: Thu, 9 Mar 2023 03:04:15 -0600 Subject: [PATCH] Tidy: Docstrings --- org-ql-search.el | 27 ++++++++++++++++++--------- org-ql.el | 41 ++++++++++++++++++++++++++--------------- 2 files changed, 44 insertions(+), 24 deletions(-) diff --git a/org-ql-search.el b/org-ql-search.el index c98f1e47..1d47be33 100644 --- a/org-ql-search.el +++ b/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) - (list org-directory) - (user-error "Org-ql-search-directories-files: No DIRECTORIES given, and `org-directory' doesn't exist"))) + (&key (directories + (if (file-exists-p org-directory) + (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 diff --git a/org-ql.el b/org-ql.el index 10438096..22fa86f0 100644 --- a/org-ql.el +++ b/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. -If NARROW is non-nil, buffer will not be widened." + "Return results for given arguments. +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 COMPARATOR NUMBER): Matches if heading level compares to NUMBER with COMPARATOR. + (level NUMBER NUMBER): Matches if heading level is equal to or between + 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