heavy linting effort

README.org

@@ -1,9 +1,9 @@
 * NOTICE
-This is org-gtd 2.0.0.
+This is org-gtd 3.0.0.
 
 Check documentation in [[doc/]] (and the info manual within emacs itself) if you're upgrading. Please report all defects as Github issues.
 
-Use existing tags if you'd rather stick to a pre-2.0 version.
+Use existing tags if you'd rather stick to a pre-3.0 version.
 
 * Sponsorship
 I've put many hours of reading, research, and coding, to put this together. If it delivers value to you, helps you manage your life, please consider sponsoring ([[https://github.com/sponsors/Trevoke/][Github sponsors]] or [[https://www.patreon.com/LokiConsulting][Patreon]]) and allowing me to continue putting work into this package and other projects.

org-gtd-agenda.el

@@ -75,7 +75,6 @@ This assumes all GTD files are also agenda files."
       (org-gtd-core-prepare-agenda-buffers)
       (org-todo-list org-gtd-next)))
 
-;;;###autoload
 (defun org-gtd-agenda--apply (func)
   "Run FUNC on a single task shown in the agenda view."
   (interactive)
@@ -172,7 +171,7 @@ This function is intended to be used on incubated items that come up."
        (org-agenda-show-tags)))))
 
 (defun org-gtd-agenda--prefix-format ()
-  "format prefix for items in buffer"
+  "Format prefix for items in agenda buffer."
   (let* ((elt (org-element-at-point))
          (level (org-element-property :level elt))
          (category (org-entry-get (point) "CATEGORY" t))

org-gtd-archive.el

@@ -68,6 +68,7 @@ into a datetree."
     (delete-file temp-file)))
 
 (defun org-gtd-archive-location-func ()
+  "Default function to define where to archive items."
   (let* ((year (number-to-string (caddr (calendar-current-date))))
          (full-org-gtd-path (expand-file-name org-gtd-directory))
          (filename (format org-gtd-archive-file-format year))
@@ -108,8 +109,7 @@ or `org-gtd-canceled'."
    'agenda))
 
 (defun org-gtd--all-subheadings-in-done-type-p ()
-  "Private function. Returns t if every sub-heading is in a `org-gtd-done' or
-`org-gtd-canceled' state."
+  "Return t if every sub-heading is `org-gtd-done' or `org-gtd-canceled'."
   (seq-every-p (lambda (x) (eq x 'done))
                (org-map-entries (lambda ()
                                   (org-element-property :todo-type (org-element-at-point)))

org-gtd-calendar.el

@@ -60,6 +60,7 @@ actually appointments or deadlines."
 
 ;;;###autoload
 (defun org-gtd-calendar ()
+  "Decorate and refile item at point as a calendar item."
   (interactive)
   (org-gtd-organize--call org-gtd-calendar-func))
 

org-gtd-clarify.el

@@ -20,7 +20,7 @@
 
 ;;; Commentary:
 ;;
-;; Set up emacs to helpfully clarify tasks so they can then be organized.
+;; Set up Emacs to helpfully clarify tasks so they can then be organized.
 ;;
 ;;; Code:
 
@@ -32,7 +32,7 @@
   :group 'org-gtd)
 
 (defcustom org-gtd-clarify-show-horizons nil
-  "When t, show a side buffer with the higher horizons during item clarification.
+  "If t, show a side buffer with the higher horizons during item clarification.
 The file shown can be configured in `org-gtd-horizons-file'"
   :package-version '(org-gtd . "3.0")
   :group 'org-gtd-clarify
@@ -101,8 +101,8 @@ The file shown can be configured in `org-gtd-horizons-file'"
 
 ;;;###autoload
 (defun org-gtd-clarify-inbox-item ()
-  "Process item at point through org-gtd. This function is called through the
-inbox clarification process."
+  "Process item at point through org-gtd.
+This function is called through the inbox clarification process."
   (interactive)
   (org-gtd-clarify-item)
   (setq-local org-gtd-clarify--inbox-p t))
@@ -118,7 +118,7 @@ inbox clarification process."
       (message "There are no Org-GTD WIP buffers."))))
 
 (defun org-gtd-clarify-setup-windows (buffer-or-name)
-  "Setup clarifying windows around BUFFER."
+  "Setup clarifying windows around BUFFER-OR-NAME."
   (let ((buffer (get-buffer buffer-or-name)))
     (set-buffer buffer)
     (display-buffer buffer)

org-gtd-core.el

@@ -49,20 +49,20 @@ your own files if you want multiple refile targets (projects, etc.)."
 (defcustom org-gtd-horizons-file "horizons.org"
   "File holding your GTD horizons.
 
-This may get displayed during item clarification for context and focus. This file
-must be in the `org-gtd-directory'."
+This may get displayed during item clarification for context and focus.
+This file must be in the `org-gtd-directory'."
   :group 'org-gtd
   :package-version '(org-gtd . "3.0")
   :type 'file)
 
 (defcustom org-gtd-next "NEXT"
-  "The org-mode keyword for an action ready to be done. Just the word."
+  "The `org-mode' keyword for an action ready to be done.  Just the word."
   :group 'org-gtd
   :package-version '(org-gtd . "3.0")
   :type 'string)
 
 (defcustom org-gtd-next-suffix "(n)"
-  "Additional org-mode tools for this keyword. Example: \"(w@/!)\".
+  "Additional `org-mode' tools for this keyword.  Example: \"(w@/!)\".
 
 You can define:
 - a key to be used with `org-use-fast-todo-selection'
@@ -75,15 +75,15 @@ See `org-todo-keywords' for definition."
   :type 'string)
 
 (defcustom org-gtd-todo "TODO"
-  "The org-mode keyword for an upcoming action (not yet ready, not blocked).
+  "The `org-mode' keyword for an upcoming action (not yet ready, not blocked).
 
 See `org-todo-keywords' for customization options."
   :group 'org-gtd
   :package-version '(org-gtd . "3.0")
   :type 'string)
 
 (defcustom org-gtd-todo-suffix "(t)"
-  "Additional org-mode tools for this keyword. Example: \"(w@/!)\".
+  "Additional `org-mode' tools for this keyword.  Example: \"(w@/!)\".
 
 You can define:
 - a key to be used with `org-use-fast-todo-selection'
@@ -96,15 +96,15 @@ See `org-todo-keywords' for definition."
   :type 'string)
 
 (defcustom org-gtd-wait "WAIT"
-  "The org-mode keyword when an action is blocked/delegated.
+  "The `org-mode' keyword when an action is blocked/delegated.
 
 See `org-todo-keywords' for customization options."
   :group 'org-gtd
   :package-version '(org-gtd . "3.0")
   :type 'string)
 
 (defcustom org-gtd-wait-suffix "(w@)"
-  "Additional org-mode tools for this keyword. Example: \"(w@/!)\".
+  "Additional `org-mode' tools for this keyword.  Example: \"(w@/!)\".
 
 You can define:
 - a key to be used with `org-use-fast-todo-selection'
@@ -117,15 +117,15 @@ See `org-todo-keywords' for definition."
   :type 'string)
 
 (defcustom org-gtd-done "DONE"
-  "The org-mode keyword for a finished task.
+  "The `org-mode' keyword for a finished task.
 
  See `org-todo-keywords' for customization options."
   :group 'org-gtd
   :package-version '(org-gtd . "3.0")
   :type 'string)
 
 (defcustom org-gtd-done-suffix "(d)"
-  "Additional org-mode tools for this keyword. Example: \"(w@/!)\".
+  "Additional `org-mode' tools for this keyword.  Example: \"(w@/!)\".
 
 You can define:
 - a key to be used with `org-use-fast-todo-selection'
@@ -138,15 +138,15 @@ See `org-todo-keywords' for definition."
   :type 'string)
 
 (defcustom org-gtd-canceled "CNCL"
-  "The org-mode keyword for a canceled task.
+  "The `org-mode' keyword for a canceled task.
 
  See `org-todo-keywords' for customization options."
   :group 'org-gtd
   :package-version '(org-gtd . "3.0")
   :type 'string)
 
 (defcustom org-gtd-canceled-suffix "(c@)"
-  "Additional org-mode tools for this keyword. Example: \"(w@/!)\".
+  "Additional `org-mode' tools for this keyword.  Example: \"(w@/!)\".
 
 You can define:
 - a key to be used with `org-use-fast-todo-selection'
@@ -178,7 +178,7 @@ See `org-todo-keywords' for definition."
 
 ;;;###autoload
 (defmacro with-org-gtd-context (&rest body)
-  "Wrap any BODY in this macro to inherit the org-gtd settings for your logic."
+  "Wrap BODY... in this macro to inherit the org-gtd settings for your logic."
   (declare (debug t) (indent 2))
   `(let* ((org-use-property-inheritance "ORG_GTD")
           (org-todo-keywords `((sequence ,(string-join `(,org-gtd-next ,org-gtd-next-suffix))
@@ -202,22 +202,23 @@ See `org-todo-keywords' for definition."
          (progn ,@body))))
 
 (defun org-gtd-core-prepare-buffer (&optional buffer)
-  "Make sure BUFFER is prepared to handle Org GTD operations. If BUFFER is nil,
-use current buffer."
+  "Make sure BUFFER is prepared to handle Org GTD operations.
+
+If BUFFER is nil, use current buffer."
   (with-current-buffer (or buffer (current-buffer))
     (unless (bound-and-true-p org-gtd--loading-p)
       (setq-local org-gtd--loading-p t)
       (with-org-gtd-context
           (org-mode-restart)))))
 
 (defun org-gtd-core-prepare-agenda-buffers ()
+  "Ensure `org-mode' has the desired settings in the agenda buffers."
   (mapc
    (lambda (file) (org-gtd-core-prepare-buffer (find-file-noselect file)))
    (with-org-gtd-context (org-agenda-files))))
 
 (defun org-gtd-core--agenda-files ()
-  "Return the value of the `org-agenda-files' variable with `org-gtd-directory'
-added to it."
+  "Concatenate `org-agenda-files' variable with `org-gtd-directory' contents."
   (if (stringp org-agenda-files)
       (append (org-read-agenda-file-list)
               (ensure-list org-gtd-directory))

org-gtd-delegate.el

@@ -45,18 +45,19 @@ Needs to return a string that will be used as the persons name."
 
 ;;;###autoload
 (defun org-gtd-delegate ()
+  "Organize and refile item at point as a delegated item."
   (interactive)
   (org-gtd-organize--call org-gtd-organize-delegate-func))
 
 (defun org-gtd-delegate--apply ()
-  "Delegate this item and file it in the org-gtd system."
+  "Organize, decoare refile this as a delegated item in the `org-gtd' system."
   (org-gtd-delegate-item-at-point)
   (org-gtd-organize-decorate-item)
   (org-gtd--refile org-gtd-actions))
 
 ;;;###autoload
 (defun org-gtd-delegate-item-at-point ()
-  "Delegate item at point. Most useful to delegate a project task."
+  "Delegate item at point.  Use this if you do not want to refile the item."
   (interactive)
   (let ((delegated-to (apply org-gtd-delegate-read-func nil))
         (date (org-read-date t nil nil "When do you want to check in on this task? "))

org-gtd-files.el

@@ -51,6 +51,7 @@ This is the inbox. Everything goes in here when you capture it.
     path))
 
 (defun org-gtd--horizons-file ()
+  "Create or return the buffer to the file containing the GTD horizons."
   (let ((path (f-join org-gtd-directory org-gtd-horizons-file)))
     (org-gtd--ensure-file-exists path org-gtd-file-horizons-template)
     (find-file-noselect path)))

org-gtd-id.el

@@ -47,13 +47,16 @@ This function is a modified copy of `org-id-get'."
         id))))
 
 (defun org-gtd-id--generate-sanitized-alnum-dash-string (str)
-  "Returns a string which contains only a-zA-Z0-9 with single dashes
- replacing all other characters in-between them.
+  "Clean up STR and make it fit to be used as an org id.
 
- Some parts were copied and adapted from org-hugo-slug
- from https://github.com/kaushalmodi/ox-hugo (GPLv3).
+Returns a string which contains only a-zA-Z0-9 with single dashes replacing
+all other characters in-between them.
 
-Taken from https://gitlab.com/publicvoit/orgmode-link-demo/-/raw/main/link_demo.org."
+Some parts were copied and adapted from org-hugo-slug from
+https://github.com/kaushalmodi/ox-hugo (GPLv3).
+
+Taken from
+https://gitlab.com/publicvoit/orgmode-link-demo/-/raw/main/link_demo.org ."
   (let* (;; Remove "<FOO>..</FOO>" HTML tags if present.
          (str (replace-regexp-in-string "<\\(?1:[a-z]+\\)[^>]*>.*</\\1>" "" str))
          ;; Remove URLs if present in the string.  The ")" in the
@@ -100,9 +103,9 @@ Taken from https://gitlab.com/publicvoit/orgmode-link-demo/-/raw/main/link_demo.
     str))
 
 (defun org-gtd-id--generate()
-  "Generates and returns a new id.
+  "Generate and return a new id.
 The generated ID is stripped off potential progress indicator cookies and
-sanitized to get a slug. Furthermore, it is suffixed with an ISO date-stamp."
+sanitized to get a slug.  Furthermore, it is suffixed with an ISO date-stamp."
   (let* ((my-heading-text (nth 4 (org-heading-components))) ;; retrieve heading string
          (my-heading-text (replace-regexp-in-string "\\(\\[[0-9]+%\\]\\)" "" my-heading-text)) ;; remove progress indicators like "[25%]"
          (my-heading-text (replace-regexp-in-string "\\(\\[[0-9]+/[0-9]+\\]\\)" "" my-heading-text)) ;; remove progress indicators like "[2/7]"

org-gtd-incubate.el

@@ -36,6 +36,7 @@
 
 ;;;###autoload
 (defun org-gtd-incubate ()
+  "Decorate, organize and refile item at point as incubated."
   (interactive)
   (org-gtd-organize--call org-gtd-organize-incubate-func))
 

org-gtd-knowledge.el

@@ -40,6 +40,7 @@ clarify step, before you call `org-gtd-organize')."
 
 ;;;###autoload
 (defun org-gtd-knowledge ()
+  "Decorate, organize and refile item at point as knowledge."
   (interactive)
   (org-gtd-organize--call org-gtd-knowledge-func))
 

org-gtd-process.el

@@ -44,7 +44,7 @@ the items once they have been processed and add them to that list."
 
 ;;;###autoload
 (defun org-gtd-process-inbox ()
-  "New stuff whodis"
+  "Start the inbox processing item, one heading at a time."
   (interactive)
   (set-buffer (org-gtd--inbox-file))
 

org-gtd-projects.el

@@ -32,9 +32,11 @@
 (require 'org-gtd-agenda)
 
 (defun org-edna-action/org-gtd-update-project-task! (_last-entry)
+  "`org-edna' extension to change the todo state to `org-gtd-next'."
   (org-todo org-gtd-next))
 
 (defun org-edna-finder/org-gtd-next-project-action ()
+  "`org-edna' extension to find the next action to show in the agenda."
   (org-edna-finder/relatives 'forward-no-wrap 'todo-only 1 'no-sort))
 
 (defcustom org-gtd-organize-project-func
@@ -56,7 +58,7 @@ depend on the way org-gtd structures and organizes the projects."
 
 (defconst org-gtd-project-headings
   "+LEVEL=2&+ORG_GTD=\"Projects\""
-  "How to tell org-mode to find project headings")
+  "How to tell `org-mode' to find project headings.")
 
 (defconst org-gtd-stuck-projects
   `(,org-gtd-project-headings
@@ -83,19 +85,22 @@ instead.")
 
 ;;;###autoload
 (defun org-gtd-project-new ()
+  "Organize, decorate and refile item as a new project."
   (interactive)
   (org-gtd-organize--call org-gtd-organize-project-func))
 
 ;;;###autoload
 (defun org-gtd-project-extend ()
+  "Organize, decorate and refile item as a new task in an existing project."
   (interactive)
   (org-gtd-organize--call org-gtd-organize-add-to-project-func))
 
 (defun org-gtd-project-new--apply ()
   "Process GTD inbox item by transforming it into a project.
-Allow the user apply user-defined tags from
-`org-tag-persistent-alist', `org-tag-alist' or file-local tags in
-the inbox.  Refile to `org-gtd-actionable-file-basename'."
+
+Allow the user apply user-defined tags from `org-tag-persistent-alist',
+`org-tag-alist' or file-local tags in the inbox.
+Refile to `org-gtd-actionable-file-basename'."
   (when (org-gtd-projects--poorly-formatted-p)
     (org-gtd-projects--show-error)
     (throw 'org-gtd-error "Malformed project"))
@@ -153,14 +158,15 @@ the inbox.  Refile to `org-gtd-actionable-file-basename'."
   "Ensure keywords for subheadings of project at point are sane.
 
 This means one and only one `org-gtd-next' keyword, and it is the first non-done
-state in the list - all others are `org-gtd-todo'.."
+state in the list - all others are `org-gtd-todo'."
   (interactive)
   (org-gtd-projects-fix-todo-keywords (point-marker)))
 
 (defun org-gtd-projects-fix-todo-keywords (marker)
-  "Ensure project at MARKER has only one `org-gtd-next' keyword. Ensures only
-the first non-done keyword is `org-gtd-next', all other non-done are
-`org-gtd-todo'."
+  "Ensure project at MARKER has only one `org-gtd-next' keyword.
+
+Ensures only the first non-done keyword is `org-gtd-next', all other non-done
+are `org-gtd-todo'."
   (with-current-buffer (marker-buffer marker)
     (org-gtd-core-prepare-buffer)
     (save-excursion
@@ -170,8 +176,7 @@ the first non-done keyword is `org-gtd-next', all other non-done are
        (lambda ()
          (unless (member
                   (org-element-property :todo-keyword (org-element-at-point))
-                  `(,org-gtd-todo ,org-gtd-wait ,org-gtd-done ,org-gtd-canceled)
-                  )
+                  `(,org-gtd-todo ,org-gtd-wait ,org-gtd-done ,org-gtd-canceled))
            (org-entry-put (org-gtd-projects--org-element-pom (org-element-at-point))
                           "TODO" org-gtd-todo)))
        "+LEVEL=3" 'tree))