diff --git a/lisp/cli/ci.el b/lisp/cli/ci.el index a9977e8e8..9f5473d1a 100644 --- a/lisp/cli/ci.el +++ b/lisp/cli/ci.el @@ -56,7 +56,7 @@ Each element of this list can be one of: '(docs \"faq\" \"install\" check-docs)") (defvar doom-ci-commit-rules - ;; TODO Extract into named functions + ;; TODO: Extract into named functions (list (lambda! (&key subject) "If a fixup/squash commit, don't lint this commit" (when (string-match "^\\(\\(?:fixup\\|squash\\)!\\|FIXUP\\|WIP\\) " subject) @@ -169,7 +169,7 @@ Each element of this list can be one of: (fail! "%d commit hash(s) not 12 characters long: %s" (length refs) (string-join (nreverse refs) ", ")))))) - ;; TODO Add bump validations for revert: type. + ;; TODO: Add bump validations for revert: type. (lambda! (&key body trailers) "Validate commit trailers." (let* ((keys (mapcar #'car doom-ci-commit-trailer-keys)) @@ -206,10 +206,10 @@ Each element of this list can be one of: (fail! "%S expects one of %s, but got %S" key allowed-types value))))))) - ;; TODO Check that bump/revert SUBJECT list: 1) valid modules and 2) - ;; modules whose files are actually being touched. + ;; TODO: Check that bump/revert SUBJECT list: 1) valid modules and 2) + ;; modules whose files are actually being touched. - ;; TODO Ensure your diff corraborates your SCOPE + ;; TODO: Ensure your diff corraborates your SCOPE ) "A list of validator functions to run against a commit. @@ -252,7 +252,7 @@ Note: warnings are not considered failures.") "Commands that automate development processes." :partial t) -;; TODO Move to 'doom install --git-hooks' +;; TODO: Move to 'doom install --git-hooks' (defcli! (ci deploy-hooks) ((force ("--force"))) "TODO" (let* ((repo-path (sh! "git" "rev-parse" "--show-toplevel")) @@ -284,7 +284,7 @@ Note: warnings are not considered failures.") (if overwrite-p "Overwrote" "Created") (path hook)))))) -;; TODO Move to 'doom lint commits' +;; TODO: Move to 'doom lint commits' (defcli! (ci lint-commits) (from &optional to) "TODO" (with-temp-buffer @@ -307,7 +307,7 @@ Note: warnings are not considered failures.") commits)) commits)))) -;; TODO Move to 'doom lint hook:commit-msg' +;; TODO: Move to 'doom lint hook:commit-msg' (defcli! (ci hook commit-msg) (file) "Run git commit-msg hook. @@ -323,7 +323,7 @@ Lints the current commit message." (point-max))))) t))) -;; TODO Move to 'doom lint hook:pre-push' +;; TODO: Move to 'doom lint hook:pre-push' (defcli! (ci hook pre-push) (remote url) "Run git pre-push hook. @@ -335,7 +335,7 @@ Prevents pushing if there are unrebased or WIP commits." (catch 'continue (seq-let (local-ref local-sha remote-ref remote-sha) (split-string line " ") - ;; TODO Extract this branch detection to a variable + ;; TODO: Extract this branch detection to a variable (unless (or (string-match-p "^refs/heads/\\(master\\|main\\)$" remote-ref) (equal local-sha z40)) (throw 'continue t)) diff --git a/lisp/cli/emacs.el b/lisp/cli/emacs.el index 9b6d9a58a..a7c4a33e1 100644 --- a/lisp/cli/emacs.el +++ b/lisp/cli/emacs.el @@ -15,7 +15,7 @@ ;;; Commands (defcli! emacs - (;; TODO Implement sandbox functionality post-3.0 + (;; TODO: Implement sandbox functionality post-3.0 ;; (daemon? ("--daemon")) ;; (window-type ("--gui" "--tty")) ;; (version ("--with-emacs" version)) diff --git a/lisp/cli/env.el b/lisp/cli/env.el index 8e6f9a042..37ff63c4a 100644 --- a/lisp/cli/env.el +++ b/lisp/cli/env.el @@ -54,7 +54,7 @@ variable names to omit from `doom-env-file'.") ((allow-only ("--allow-all")) (deny-only ("--deny-all")) (output-file ("-o" path) "Write envvar file to non-standard PATH.") - ;; TODO (refresh? ("-r" "--refresh")) + ;; TODO: (refresh? ("-r" "--refresh")) &multiple (rules ("-a" "--allow" "-d" "--deny" regexp) "Allow/deny envvars that match REGEXP")) "(Re)generates envvars file from your shell environment. diff --git a/lisp/cli/make.el b/lisp/cli/make.el index ed33b4463..a60a594ff 100644 --- a/lisp/cli/make.el +++ b/lisp/cli/make.el @@ -44,7 +44,7 @@ (unless dryrun? (write-region (buffer-string) nil outfile))))))))) -;; TODO Finish me +;; TODO: Finish me (defcli-stub! (make changelog)) diff --git a/lisp/cli/make/completions.el b/lisp/cli/make/completions.el index 3402ba2aa..51add97fa 100644 --- a/lisp/cli/make/completions.el +++ b/lisp/cli/make/completions.el @@ -15,13 +15,13 @@ (defcli! (make completions) ((shell ("--zsh" "--bash") "Generate a particular flavor of completion files (defaults to $SHELL)") - ;; TODO (outfile ("-o" "--outfile" file)) + ;; TODO: (outfile ("-o" "--outfile" file)) &context context &args args) "Generate completion scripts for a Doom-CLI script." ;; (unless outfile ;; (user-error "No destination file specified")) (let ((shell (or shell (file-name-base (getenv "SHELL")))) - ;; TODO Allow this command to read other Doom binscripts, which will + ;; TODO: Allow this command to read other Doom binscripts, which will ;; dump their `doom-cli--table' if __DOOMDUMP is set. ;; (table (read (letenv! (("__DOOMDUMP" "1")) (apply #'sh! script-file args)))) ) @@ -35,7 +35,7 @@ ;; ;;; ZSH Helpers -;; TODO Write to OUTFILE when specified +;; TODO: Write to OUTFILE when specified (defun doom-make-completions-zsh (context _outfile) (let* ((cli (doom-cli-get context)) (prefix (doom-cli-context-prefix context)) @@ -59,7 +59,7 @@ )) (defun doom-make-completions--zsh-insert-options (options &optional cr) - ;; FIXME Refactor, generalize, and parameterize this mess + ;; FIXME: Refactor, generalize, and parameterize this mess (dolist (option options) (let* ((switches (cl-loop for (sw . args) in (car option) if (string-prefix-p "--[no-]" sw) diff --git a/lisp/cli/test.el b/lisp/cli/test.el index 87c878aed..4cd23a69b 100644 --- a/lisp/cli/test.el +++ b/lisp/cli/test.el @@ -12,11 +12,11 @@ ;; ;;; Variables -;; TODO Implement me +;; TODO: Implement me (defvar doom-test-backend 'ert "One of `ert' or `buttercup'.") -;; TODO Implement me +;; TODO: Implement me (defvar doom-test-isolation-level nil "Determines the testing strategy for tests. @@ -31,7 +31,7 @@ Should be one of: ;; ;;; Commands -;; FIXME Will be fixed in v3.1 +;; FIXME: Will be fixed in v3.1 (defcli-stub! test ((backend ("--ert" "--buttercup")) (jobs ("-j" "--jobs" int)) diff --git a/lisp/cli/upgrade.el b/lisp/cli/upgrade.el index 68de49286..27a11b90c 100644 --- a/lisp/cli/upgrade.el +++ b/lisp/cli/upgrade.el @@ -35,7 +35,7 @@ libraries. It is the equivalent of the following shell commands: (let ((force? (doom-cli-context-suppress-prompts-p context))) (cond (packages? - ;; HACK It's messy to use straight to upgrade straight, due to the + ;; HACK: It's messy to use straight to upgrade straight, due to the ;; potential for backwards incompatibility, so we staticly check if ;; Doom's `package!' declaration for straight has changed. If it has, ;; delete straight so 'doom sync' will install the new version for us. diff --git a/lisp/doom-cli.el b/lisp/doom-cli.el index f6ed76ec6..594bdb868 100644 --- a/lisp/doom-cli.el +++ b/lisp/doom-cli.el @@ -570,7 +570,7 @@ Throws `doom-cli-invalid-option-error' for illegal values." errors) (catch 'done (dolist (type types) - ;; REVIEW Use pcase-let + map.el when 27.x support is dropped + ;; REVIEW: Use pcase-let + map.el when 27.x support is dropped (cl-destructuring-bind (&key test read error &allow-other-keys) (if (or (symbolp type) (and (stringp type) @@ -956,7 +956,7 @@ considered as well." (defun doom-cli-debugger (type data &optional context) "Print a more presentable backtrace to terminal and write it to file." - ;; HACK Works around a heuristic in eval.c for detecting errors in the + ;; HACK: Works around a heuristic in eval.c for detecting errors in the ;; debugger, which executes this handler again on subsequent calls. Taken ;; from `ert--run-test-debugger'. (cl-incf num-nonmacro-input-events) @@ -1351,9 +1351,9 @@ ARGS are options passed to less. If DOOMPAGER is set, ARGS are ignored." 0))) context)) -;; (defun doom-cli--exit-editor (args context)) ; TODO Launch $EDITOR +;; (defun doom-cli--exit-editor (args context)) ; TODO: Launch $EDITOR -;; (defun doom-cli--exit-emacs (args context)) ; TODO Launch Emacs subsession +;; (defun doom-cli--exit-emacs (args context)) ; TODO: Launch Emacs subsession @@ -1990,7 +1990,7 @@ errors to `doom-cli-error-file')." (defalias 'sh!! #'doom-exec-process) -;; TODO Make `git!' into a more sophisticated wrapper around git +;; TODO: Make `git!' into a more sophisticated wrapper around git (defalias 'git! (doom-partial #'straight--process-run "git")) (defun get! (key) (doom-cli-context-get doom-cli--context key)) @@ -2108,7 +2108,7 @@ substring is edited more than once." current)))) ;;; Help: printers -;; TODO Parameterize optional args with `cl-defun' +;; TODO: Parameterize optional args with `cl-defun' (defun doom-cli-help--print (cli context &optional manpage? noglobal?) "Write CLI's documentation in a manpage-esque format to stdout." (let-alist (doom-cli-help cli) @@ -2118,7 +2118,7 @@ substring is edited more than once." (width (floor (/ (- (doom-cli-context-width context) (length title)) 2.0)))) - ;; FIXME Who am I fooling? + ;; FIXME: Who am I fooling? (format (format "%%-%ds%%s%%%ds" width width) "DOOM(1)" title "DOOM(1)"))) ("NAME" . ,(concat .command " - " .summary)) diff --git a/lisp/doom-editor.el b/lisp/doom-editor.el index 792445e8a..d3cabd90b 100644 --- a/lisp/doom-editor.el +++ b/lisp/doom-editor.el @@ -546,11 +546,11 @@ on." (defun doom-buffer-has-long-lines-p () (unless (bound-and-true-p visual-line-mode) (let ((so-long-skip-leading-comments - ;; HACK Fix #2183: `so-long-detected-long-line-p' calls + ;; HACK: Fix #2183: `so-long-detected-long-line-p' calls ;; `comment-forward' which tries to use comment syntax, which ;; throws an error if comment state isn't initialized, leading ;; to a wrong-type-argument: stringp error. - ;; DEPRECATED Fixed in Emacs 28. + ;; DEPRECATED: Fixed in Emacs 28. (bound-and-true-p comment-use-syntax))) (so-long-detected-long-line-p)))) (setq so-long-predicate #'doom-buffer-has-long-lines-p)) diff --git a/lisp/doom-lib.el b/lisp/doom-lib.el index a8de5847c..da8ee2ff0 100644 --- a/lisp/doom-lib.el +++ b/lisp/doom-lib.el @@ -1543,7 +1543,7 @@ in these blocks dictates their load order (unless given an explicit :depth)." modules))) t)) -;; DEPRECATED Remove in 3.0 +;; DEPRECATED: Remove in v3 (define-obsolete-function-alias 'featurep! 'modulep! "3.0.0") (defmacro modulep! (group &optional module &rest flags) @@ -1696,7 +1696,7 @@ elsewhere." (with-no-warnings (cons name plist))))) -;; DEPRECATED: Will be replaced with new `packages!' macro in v3.0 +;; DEPRECATED: Will be replaced in v3 (defmacro disable-packages! (&rest packages) "A convenience macro for disabling packages in bulk. Only use this macro in a module's (or your private) packages.el file." @@ -1704,7 +1704,7 @@ Only use this macro in a module's (or your private) packages.el file." (mapcar (lambda (p) `(package! ,p :disable t)) packages))) -;; DEPRECATED: Will be replaced with new `packages!' macro in v3.0 +;; DEPRECATED: Will be replaced in v3 (defmacro unpin! (&rest targets) "Unpin packages in TARGETS. diff --git a/lisp/doom-projects.el b/lisp/doom-projects.el index 3e3969b38..e642e8590 100644 --- a/lisp/doom-projects.el +++ b/lisp/doom-projects.el @@ -170,7 +170,7 @@ And if it's a function, evaluate it." ((when-let* ((doom-fd-executable) (projectile-git-use-fd) - ;; REVIEW Temporary fix for #6618. Improve me later. + ;; REVIEW: Temporary fix for #6618. Improve me later. (version (with-memoization (get 'doom-fd-executable 'version) (cadr (split-string (cdr (doom-call-process doom-fd-executable "--version")) " " t)))) diff --git a/lisp/doom-start.el b/lisp/doom-start.el index 7ac1eac01..9ae364c1a 100644 --- a/lisp/doom-start.el +++ b/lisp/doom-start.el @@ -293,7 +293,7 @@ If RETURN-P, return the message as a string instead of displaying it." ;; and ~/_emacs) -- and spare us the IO of searching for them, and allows ;; savvy hackers to use $EMACSDIR as their $DOOMDIR, if they wanted. ;; 3. Cut down on unnecessary logic in Emacs' bootstrapper. -;; 4. TODO Offer a more user-friendly error state/screen, especially for +;; 4. TODO: Offer a more user-friendly error state/screen, especially for ;; errors emitted from Doom's core or the user's config. (define-advice startup--load-user-init-file (:override (&rest _) init-doom 100) (let ((debug-on-error-from-init-file nil) diff --git a/lisp/doom-straight.el b/lisp/doom-straight.el index c590191cd..d397ef1fd 100644 --- a/lisp/doom-straight.el +++ b/lisp/doom-straight.el @@ -123,8 +123,8 @@ It may not be obvious to users what they should do for some straight prompts, so Doom will recommend the one that reverts a package back to its (or target) original state.") -;; HACK Remove dired & magit options from prompt, since they're inaccessible in -;; noninteractive sessions. +;; HACK: Remove dired & magit options from prompt, since they're inaccessible in +;; noninteractive sessions. (advice-add #'straight-vc-git--popup-raw :override #'straight--popup-raw) ;; HACK: `native-comp' only respects `native-comp-jit-compilation-deny-list' @@ -152,8 +152,8 @@ original state.") file-list) recursively load selector))) -;; HACK Replace GUI popup prompts (which hang indefinitely in tty Emacs) with -;; simple prompts. +;; HACK: Replace GUI popup prompts (which hang indefinitely in tty Emacs) with +;; simple prompts. (defadvice! doom-straight--fallback-to-y-or-n-prompt-a (fn &optional prompt noprompt?) :around #'straight-are-you-sure (or noprompt? diff --git a/lisp/doom-ui.el b/lisp/doom-ui.el index b4a0803f9..17f673ac7 100644 --- a/lisp/doom-ui.el +++ b/lisp/doom-ui.el @@ -559,8 +559,8 @@ windows, switch to `doom-fallback-buffer'. Otherwise, delegate to original #'display-line-numbers-mode) ;; Fix #2742: cursor is off by 4 characters in `artist-mode' -;; REVIEW Reported upstream https://debbugs.gnu.org/cgi/bugreport.cgi?bug=43811 -;; DEPRECATED Fixed in Emacs 28; remove when we drop 27 support +;; REVIEW: Reported upstream https://debbugs.gnu.org/cgi/bugreport.cgi?bug=43811 +;; DEPRECATED: Fixed in Emacs 28; remove when we drop 27 support (unless (> emacs-major-version 27) (add-hook 'artist-mode-hook #'doom-disable-line-numbers-h)) diff --git a/lisp/doom.el b/lisp/doom.el index 816d82643..c1c705b60 100644 --- a/lisp/doom.el +++ b/lisp/doom.el @@ -237,7 +237,7 @@ (cons (match-string 1 profile) (match-string 2 profile)) (cons profile "0"))) - ;; TODO Restore this in 3.0 + ;; TODO: Restore this in v3 ;; (cons "_" "0") ) "The active profile as a cons cell (NAME . VERSION).") diff --git a/lisp/lib/debug.el b/lisp/lib/debug.el index c0b22fa65..a63128710 100644 --- a/lisp/lib/debug.el +++ b/lisp/lib/debug.el @@ -372,7 +372,7 @@ FILL-COLUMN determines the column at which lines will be broken." (let ((doom-print-backend (unless nocolor doom-print-backend)) (doom-print-indent 0)) (dolist (spec (cl-remove-if-not #'cdr (doom-info)) (buffer-string)) - ;; FIXME Refactor this horrible cludge, either here or in `format!' + ;; REVIEW: Refactor this horrible cludge, either here or in `format!' (insert! ((bold "%-10s ") (symbol-name (car spec))) ("%s\n" (string-trim-left @@ -406,7 +406,7 @@ FILL-COLUMN determines the column at which lines will be broken." "git" "-C" (expand-file-name doom-emacs-dir) "log" "-1" "--format=%D %h %ci")) "n/a")) - ;; NOTE This is a placeholder. Our modules will be moved to its own + ;; NOTE: This is a placeholder. Our modules will be moved to its own ;; repo eventually, and Doom core will later be capable of managing ;; them like package sources. (format "%-13s v%-15s %s" diff --git a/lisp/lib/docs.el b/lisp/lib/docs.el index 2539c257e..cd0dd8ea6 100644 --- a/lisp/lib/docs.el +++ b/lisp/lib/docs.el @@ -157,7 +157,7 @@ (set-buffer-modified-p nil) (org-link-open (org-element-context))))) -;; DEPRECATED Will be renamed once docs "framework" is generalized +;; DEPRECATED: Will be renamed once docs "framework" is generalized (defvar doom-docs-link-alist '(("doom-tag" . "https://github.com/hlissner/doom-emacs/releases/tag/%s") ("doom-contrib-core" . "id:9ac0c15c-29e7-43f8-8926-5f0edb1098f0") @@ -177,7 +177,7 @@ ("doom-suggest-faq" . "id:aa28b732-0512-49ed-a47b-f20586c0f051") ("github" . "https://github.com/%s") - ;; TODO Implement later, once docs are generalized + ;; TODO: Implement later, once docs are generalized ;; ("github-release" . (lambda (link) ;; (format "%s/releases/tag/%s" ;; doom-docs-this-repo diff --git a/lisp/lib/files.el b/lisp/lib/files.el index c6121d47f..00d6b04b9 100644 --- a/lisp/lib/files.el +++ b/lisp/lib/files.el @@ -207,7 +207,7 @@ single file or nested compound statement of `and' and `or' statements." (if (executable-find "du") (/ (string-to-number (cdr (doom-call-process "du" "-sb" dir))) 1024.0) - ;; REVIEW This is slow and terribly inaccurate, but it's something + ;; REVIEW: This is slow and terribly inaccurate, but it's something (let ((w32-get-true-file-attributes t) (file-name-handler-alist dir) (max-lisp-eval-depth 5000) diff --git a/lisp/lib/git.el b/lisp/lib/git.el index 9f91ee97c..c1ca8a959 100644 --- a/lisp/lib/git.el +++ b/lisp/lib/git.el @@ -9,7 +9,7 @@ (doom-call-process "git" "rev-parse" "--show-toplevel") (if (zerop code) (apply #'file-name-concat output segments) - ;; TODO throw stderr as error + ;; TODO: throw stderr as error (user-error "Not in a git repo: %s" default-directory)))) (provide 'doom-lib '(git)) diff --git a/lisp/lib/help.el b/lisp/lib/help.el index 1426ec8f8..18c7154be 100644 --- a/lisp/lib/help.el +++ b/lisp/lib/help.el @@ -329,7 +329,7 @@ without needing to check if they are available." (autodef (completing-read "Describe setter: " - ;; TODO Could be cleaner (refactor me!) + ;; REVIEW: Could be cleaner (refactor me!) (cl-loop with maxwidth = (apply #'max (mapcar #'length (mapcar #'symbol-name settings))) for def in (sort settings #'string-lessp) if (get def 'doom-module) @@ -379,7 +379,7 @@ without needing to check if they are available." (unless (eq (char-after) ?\() (backward-char)) (let ((sexp (sexp-at-point))) - ;; DEPRECATED `featurep!' + ;; DEPRECATED: `featurep!' is deprecated (when (memq (car-safe sexp) '(featurep! modulep! require!)) (format "%s %s" (nth 1 sexp) (nth 2 sexp))))))) ((when buffer-file-name @@ -551,7 +551,7 @@ If prefix arg is present, refresh the cache." (format "total %d" (length packages)))) packages nil t nil nil (when guess (symbol-name guess)))))))) - ;; TODO Refactor me. + ;; REVIEW: Refactor me. (doom-initialize-packages) (help-setup-xref (list #'doom/help-packages package) (called-interactively-p 'interactive)) @@ -729,7 +729,6 @@ config blocks in your private config." (defvar counsel-rg-base-command) (defun doom--help-search (dirs query prompt) - ;; REVIEW Replace with deadgrep (unless doom-ripgrep-executable (user-error "Can't find ripgrep on your system")) (cond ((fboundp 'consult--grep) @@ -741,7 +740,7 @@ config blocks in your private config." (concat "%s " (mapconcat #'shell-quote-argument dirs " "))) (append counsel-rg-base-command dirs)))) (counsel-rg query nil "-Lz" (concat prompt ": ")))) - ;; () TODO Helm support? + ;; TODO: Helm support? ((grep-find (string-join (append (list doom-ripgrep-executable diff --git a/lisp/lib/packages.el b/lisp/lib/packages.el index f3895e5d1..398614e7c 100644 --- a/lisp/lib/packages.el +++ b/lisp/lib/packages.el @@ -473,7 +473,7 @@ also be a list of module keys." (defun doom/reload-packages () "Reload `doom-packages', `package' and `quelpa'." (interactive) - ;; HACK straight.el must be loaded for this to work + ;; HACK: straight.el must be loaded for this to work (message "Reloading packages") (doom-initialize-packages t) (message "Reloading packages...DONE")) @@ -850,8 +850,8 @@ Must be run from a magit diff buffer." (defun doom-packages--elc-file-outdated-p (file) "Check whether the corresponding .elc for `file' is outdated." (let ((elc-file (byte-compile-dest-file file))) - ;; NOTE Ignore missing elc files, they could be missing due to - ;; `no-byte-compile'. Rebuilding unnecessarily is expensive. + ;; Ignore missing elc files, they could be missing due to `no-byte-compile'. + ;; Rebuilding unnecessarily is expensive. (when (and (file-exists-p elc-file) (file-newer-than-file-p file elc-file)) (doom-log "packages:elc: %s is newer than %s" file elc-file) diff --git a/lisp/lib/plist.el b/lisp/lib/plist.el index f8f9a29df..d062ab529 100644 --- a/lisp/lib/plist.el +++ b/lisp/lib/plist.el @@ -5,7 +5,7 @@ ;; ;;; Macros -;;; DEPRECATED In favor of `cl-callf' +;;; DEPRECATED: In favor of `cl-callf' ;;;###autoload (defmacro plist-put! (plist &rest rest) "Set each PROP VALUE pair in REST to PLIST in-place." diff --git a/lisp/lib/print.el b/lisp/lib/print.el index 407fa4a2b..ea91d3760 100644 --- a/lisp/lib/print.el +++ b/lisp/lib/print.el @@ -410,7 +410,7 @@ based on the print level of the message. For example: ```" (if (not text) "" (let ((case-fold-search nil)) - ;; TODO Syntax highlighting? + ;; TODO: Syntax highlighting? (replace-regexp-in-string " *```\n\\(.+?\\)\n *```" (doom-print--style 'blue "%s" "\\1") (replace-regexp-in-string diff --git a/lisp/lib/process.el b/lisp/lib/process.el index f18ebd021..97a0d0ef8 100644 --- a/lisp/lib/process.el +++ b/lisp/lib/process.el @@ -22,7 +22,7 @@ simulate 'exec' in the shell, so batch scripts could run external programs synchronously without sacrificing their output. Warning: freezes indefinitely on any stdin prompt." - ;; FIXME Is there any way to handle prompts? + ;; FIXME: Is there any way to handle prompts? (with-temp-buffer (cons (let ((process (make-process :name "doom-sh" diff --git a/lisp/lib/projects.el b/lisp/lib/projects.el index 6bdc2e76e..09f4d6afc 100644 --- a/lisp/lib/projects.el +++ b/lisp/lib/projects.el @@ -1,10 +1,10 @@ ;;; lisp/lib/projects.el -*- lexical-binding: t; -*- -;; HACK We forward declare these variables because they are let-bound in a -;; number of places with no guarantee that they've been defined yet (i.e. -;; that `projectile' is loaded). If a variable is defined with `defvar' -;; while it is lexically bound, you get "Defining as dynamic an already -;; lexical var" errors in Emacs 28+). +;; HACK: We forward declare these variables because they are let-bound in a +;; number of places with no guarantee that they've been defined yet (i.e. +;; that `projectile' is loaded). If a variable is defined with `defvar' while +;; it is lexically bound, you get "Defining as dynamic an already lexical var" +;; errors in Emacs 28+). ;;;###autoload (defvar projectile-project-root nil) ;;;###autoload (defvar projectile-enable-caching (not noninteractive)) ;;;###autoload (defvar projectile-require-project-root 'prompt) diff --git a/lisp/lib/sandbox.el b/lisp/lib/sandbox.el index 273e567ca..f8e69b07c 100644 --- a/lisp/lib/sandbox.el +++ b/lisp/lib/sandbox.el @@ -99,8 +99,8 @@ (add-to-list 'treesit-extra-load-path ,(file-name-concat doom-profile-data-dir "tree-sitter"))) (with-eval-after-load 'undo-tree - ;; HACK `undo-tree' sometimes throws errors because - ;; `buffer-undo-tree' isn't correctly initialized. + ;; HACK: `undo-tree' sometimes throws errors because + ;; `buffer-undo-tree' isn't correctly initialized. (setq-default buffer-undo-tree (make-undo-tree))) ;; Then launch as much about Emacs as we can (defun --run-- () ,forms) diff --git a/lisp/lib/themes.el b/lisp/lib/themes.el index f9c0bf0fc..035b02104 100644 --- a/lisp/lib/themes.el +++ b/lisp/lib/themes.el @@ -48,7 +48,7 @@ all themes. It will apply to all themes once they are loaded." (when (or (get 'doom-theme 'history) (null doom-theme)) (doom--run-customize-theme-hook #',fn)) - ;; FIXME Prevent clobbering this on-the-fly + ;; FIXME: Prevent clobbering this on-the-fly (add-hook 'doom-customize-theme-hook #',fn 100)))) ;;;###autoload diff --git a/modules/checkers/spell/autoload/+flyspell.el b/modules/checkers/spell/autoload/+flyspell.el index a8ec30520..665f8d54e 100644 --- a/modules/checkers/spell/autoload/+flyspell.el +++ b/modules/checkers/spell/autoload/+flyspell.el @@ -82,5 +82,5 @@ or session. Otherwise, the addition is permanent." (call-interactively (if (featurep 'evil) #'evil-prev-flyspell-error - ;; TODO Implement this + ;; TODO: Implement this (user-error "Not supported")))) diff --git a/modules/checkers/spell/config.el b/modules/checkers/spell/config.el index 41efb27c5..5bd3173e3 100644 --- a/modules/checkers/spell/config.el +++ b/modules/checkers/spell/config.el @@ -144,9 +144,9 @@ (when-let (excluded (cdr (cl-find-if #'derived-mode-p +spell-excluded-faces-alist :key #'car))) (setq-local spell-fu-faces-exclude excluded)))) - ;; TODO custom `spell-fu-check-range' function to reduce false positives - ;; more intelligently, or modify `spell-fu-word-regexp' to include - ;; non-latin charactersets. + ;; TODO: custom `spell-fu-check-range' function to reduce false positives + ;; more intelligently, or modify `spell-fu-word-regexp' to include + ;; non-latin charactersets. ) (use-package! flyspell ; built-in diff --git a/modules/completion/company/config.el b/modules/completion/company/config.el index 20c0cfe08..bd7b5363f 100644 --- a/modules/completion/company/config.el +++ b/modules/completion/company/config.el @@ -52,10 +52,10 @@ (add-hook 'company-mode-hook #'evil-normalize-keymaps) (add-hook! 'evil-normal-state-entry-hook (defun +company-abort-h () - ;; HACK `company-abort' doesn't no-op if company isn't active; causing - ;; unwanted side-effects, like the suppression of messages in the - ;; echo-area. - ;; REVIEW Revisit this to refactor; shouldn't be necessary! + ;; HACK: `company-abort' doesn't no-op if company isn't active; causing + ;; unwanted side-effects, like the suppression of messages in the + ;; echo-area. + ;; REVIEW: Revisit this to refactor; shouldn't be necessary! (when company-candidates (company-abort)))) ;; Allow users to switch between backends on the fly. E.g. C-x C-s followed @@ -67,13 +67,13 @@ (add-hook 'company-mode-hook #'+company-init-backends-h 'append) - ;; NOTE Fix #1335: ensure `company-emulation-alist' is the first item of - ;; `emulation-mode-map-alists', thus higher priority than keymaps of - ;; evil-mode. We raise the priority of company-mode keymaps - ;; unconditionally even when completion is not activated. This should not - ;; cause problems, because when completion is activated, the value of - ;; `company-emulation-alist' is ((t . company-my-keymap)), when - ;; completion is not activated, the value is ((t . nil)). + ;; Fix #1335: ensure `company-emulation-alist' is the first item of + ;; `emulation-mode-map-alists', thus higher priority than keymaps of + ;; evil-mode. We raise the priority of company-mode keymaps unconditionally + ;; even when completion is not activated. This should not cause problems, + ;; because when completion is activated, the value of + ;; `company-emulation-alist' is ((t . company-my-keymap)), when completion is + ;; not activated, the value is ((t . nil)). (add-hook! 'evil-local-mode-hook (when (memq 'company-emulation-alist emulation-mode-map-alists) (company-ensure-emulation-alist))) @@ -141,13 +141,13 @@ (ElispFeature . ,(nerd-icons-codicon "nf-cod-globe" :face 'font-lock-builtin-face)) (ElispFace . ,(nerd-icons-codicon "nf-cod-symbol_color" :face 'success)))) - ;; HACK Fix oversized scrollbar in some odd cases - ;; REVIEW `resize-mode' is deprecated and may stop working in the future. - ;; TODO PR me upstream? + ;; HACK: Fix oversized scrollbar in some odd cases + ;; REVIEW: `resize-mode' is deprecated and may stop working in the future. + ;; TODO: PR me upstream? (setq x-gtk-resize-child-frames 'resize-mode) ;; Disable tab-bar in company-box child frames - ;; TODO PR me upstream! + ;; REVIEW: PR me upstream! (add-to-list 'company-box-frame-parameters '(tab-bar-lines . 0)) ;; Don't show documentation in echo area, because company-box displays its own @@ -164,7 +164,7 @@ ;; `company-box' performs insufficient frame-live-p checks. Any command that ;; "cleans up the session" will break company-box. - ;; TODO Fix this upstream. + ;; REVIEW: Fix this upstream. (defadvice! +company-box-detect-deleted-frame-a (frame) :filter-return #'company-box--get-frame (if (frame-live-p frame) frame)) diff --git a/modules/completion/ido/config.el b/modules/completion/ido/config.el index 0dbe51484..07d29afb6 100644 --- a/modules/completion/ido/config.el +++ b/modules/completion/ido/config.el @@ -11,8 +11,8 @@ :hook (doom-first-input . ido-mode) :hook (ido-mode . ido-ubiquitous-mode) :preface - ;; HACK `ido' is a really old package. It defines `ido-mode' manually and - ;; doesn't define a hook, so we define one for it, so we can use it! + ;; HACK: `ido' is a really old package. It defines `ido-mode' manually and + ;; doesn't define a hook, so we define one for it, so we can use it! (defadvice! +ido-run-hooks-a (&rest _) :after #'ido-mode (run-hooks 'ido-mode-hook)) diff --git a/modules/completion/ivy/autoload/ivy.el b/modules/completion/ivy/autoload/ivy.el index e904d06dc..aa0425052 100644 --- a/modules/completion/ivy/autoload/ivy.el +++ b/modules/completion/ivy/autoload/ivy.el @@ -123,7 +123,7 @@ In the GUI, this is the same as `ivy-format-function-line'." :preselect (buffer-name (other-buffer (current-buffer))) :matcher #'ivy--switch-buffer-matcher :keymap ivy-switch-buffer-map - ;; NOTE A clever disguise, needed for virtual buffers. + ;; A clever disguise, needed for virtual buffers. :caller #'ivy-switch-buffer))) ;;;###autoload @@ -322,7 +322,6 @@ If ARG (universal argument), include all files, even hidden or compressed ones." (defun +ivy/jump-list () "Go to an entry in evil's (or better-jumper's) jumplist." (interactive) - ;; REVIEW Refactor me (let (buffers) (unwind-protect (ivy-read "jumplist: " diff --git a/modules/completion/ivy/config.el b/modules/completion/ivy/config.el index ee912bc38..a258b9ccf 100644 --- a/modules/completion/ivy/config.el +++ b/modules/completion/ivy/config.el @@ -185,9 +185,9 @@ results buffer.") :config (set-popup-rule! "^\\*ivy-occur" :size 0.35 :ttl 0 :quit nil) - ;; HACK Fix an issue where `counsel-projectile-find-file-action' would try to - ;; open a candidate in an occur buffer relative to the wrong buffer, - ;; causing it to fail to find the file we want. + ;; HACK: Fix an issue where `counsel-projectile-find-file-action' would try to + ;; open a candidate in an occur buffer relative to the wrong buffer, causing + ;; it to fail to find the file we want. (defadvice! +ivy--run-from-ivy-directory-a (fn &rest args) :around #'counsel-projectile-find-file-action (let ((default-directory (ivy-state-directory ivy-last))) @@ -197,9 +197,9 @@ results buffer.") ;; of its own, on top of the defaults. (setq ivy-initial-inputs-alist nil) - ;; REVIEW Counsel allows `counsel-rg-base-command' to be a string or list. - ;; This backwards compatibility complicates things for Doom. Simpler to - ;; just force it to always be a list. + ;; REVIEW: Counsel allows `counsel-rg-base-command' to be a string or list. + ;; This backwards compatibility complicates things for Doom. Simpler to just + ;; force it to always be a list. (when (stringp counsel-rg-base-command) (setq counsel-rg-base-command (split-string counsel-rg-base-command))) @@ -267,8 +267,8 @@ workable results ripgrep produces, despite the error." (setf (nth 1 (alist-get 'ddg counsel-search-engines-alist)) "https://duckduckgo.com/?q=") - ;; REVIEW Move this somewhere else and perhaps generalize this so both - ;; ivy/helm users can enjoy it. + ;; REVIEW: Move this somewhere else and perhaps generalize this so both + ;; ivy/helm users can enjoy it. (defadvice! +ivy--counsel-file-jump-use-fd-rg-a (args) "Change `counsel-file-jump' to use fd or ripgrep, if they are available." :override #'counsel--find-return-list @@ -383,7 +383,7 @@ workable results ripgrep produces, despite the error." '(literal regexp initialism fuzzy) '(literal regexp initialism))) :config - ;; REVIEW Remove when radian-software/prescient.el#102 is resolved + ;; REVIEW: Remove when radian-software/prescient.el#102 is resolved (add-to-list 'ivy-sort-functions-alist '(ivy-resume)) (setq ivy-prescient-sort-commands '(:not swiper swiper-isearch ivy-switch-buffer lsp-ivy-workspace-symbol @@ -396,7 +396,7 @@ workable results ripgrep produces, despite the error." (let ((prescient-filter-method '(literal regexp))) (ivy-prescient-re-builder str))) - ;; NOTE prescient config duplicated with `company' + ;; Prescient config duplicated with `company': (setq prescient-save-file (file-name-concat doom-profile-cache-dir "prescient-save.el"))) diff --git a/modules/completion/vertico/autoload/vertico.el b/modules/completion/vertico/autoload/vertico.el index 7d4017b1b..61e43e6a2 100644 --- a/modules/completion/vertico/autoload/vertico.el +++ b/modules/completion/vertico/autoload/vertico.el @@ -146,7 +146,7 @@ Supports exporting consult-grep to wgrep, file to wdeired, and consult-location (unwind-protect (list (consult--read - ;; REVIEW Refactor me + ;; REVIEW: Refactor me (nreverse (delete-dups (delq @@ -217,7 +217,8 @@ targets." "Runs consult-fd if fd version > 8.6.0 exists, consult-find otherwise. See minad/consult#770." (interactive "P") - ;; TODO this condition was adapted from a similar one in lisp/doom-projects.el, to be replaced with a more robust check post v3 + ;; REVIEW: This condition was adapted from a similar one in + ;; lisp/doom-projects.el, to be replaced with a more robust check post v3 (if (when-let* ((bin (if (ignore-errors (file-remote-p default-directory nil t)) (cl-find-if (doom-rpartial #'executable-find t) @@ -227,7 +228,7 @@ See minad/consult#770." (cadr (split-string (cdr (doom-call-process bin "--version")) " " t)))) ((ignore-errors (version-to-list version)))) - ;; TODO remove once fd 8.6.0 is widespread enough to be the minimum version for doom + ;; REVIEW: Remove once fd 8.6.0 is widespread enough. (version< "8.6.0" version)) (consult-fd dir initial) (consult-find dir initial))) diff --git a/modules/config/default/+evil-bindings.el b/modules/config/default/+evil-bindings.el index 12ea2de95..9c9b62557 100644 --- a/modules/config/default/+evil-bindings.el +++ b/modules/config/default/+evil-bindings.el @@ -1,7 +1,7 @@ ;;; config/default/+bindings.el -*- lexical-binding: t; -*- (when (modulep! :editor evil +everywhere) - ;; NOTE SPC u replaces C-u as the universal argument. + ;; NOTE: SPC u replaces C-u as the universal argument. ;; Minibuffer (map! :map (evil-ex-completion-map evil-ex-search-keymap) @@ -593,10 +593,6 @@ :desc "From clipboard" "y" #'+default/yank-pop) ;;; l --- live share/collab - ;;; TODO Do you like this location for this map? This was the best idea we - ;;; could come up with, but we're happy to move it if there's a better - ;;; place! Also not sure if we're allowed to say "live share" since that's - ;;; a blatant ripoff of VS Code's name for this feature (:when (modulep! :tools collab) (:prefix-map ("l" . "live share/collab") :desc "Switch to a shared buffer" "b" #'crdt-switch-to-buffer diff --git a/modules/config/default/autoload/deferred.el b/modules/config/default/autoload/deferred.el index 4ecfb67ad..a7d886f43 100644 --- a/modules/config/default/autoload/deferred.el +++ b/modules/config/default/autoload/deferred.el @@ -1,6 +1,6 @@ ;;; config/default/autoload/deferred.el -*- lexical-binding: t; -*- -;; TODO generalize this +;; REVIEW: Generalize this ;;;###autoload (defun +default/lsp-command-map () "Lazily invoke `lsp-command-map'." diff --git a/modules/config/default/autoload/files.el b/modules/config/default/autoload/files.el index 115f71245..615fbdcf6 100644 --- a/modules/config/default/autoload/files.el +++ b/modules/config/default/autoload/files.el @@ -5,7 +5,7 @@ "Browse files from the current project's root." (interactive) (doom-project-browse (or (doom-project-root) default-directory))) -;; NOTE No need for find-in-project, use `projectile-find-file' +;; NOTE: No need for find-in-project, use `projectile-find-file' ;;;###autoload (defun +default/browse-templates () diff --git a/modules/config/default/autoload/text.el b/modules/config/default/autoload/text.el index 7a857f6ef..a4ab9c285 100644 --- a/modules/config/default/autoload/text.el +++ b/modules/config/default/autoload/text.el @@ -24,7 +24,7 @@ "Interactively select what text to insert from the kill ring." (interactive) (call-interactively - (cond ((fboundp 'consult-yank-pop) #'consult-yank-pop) ;HACK see @ymarco's comment on #5013 and TODO.org in the selecturm module. + (cond ((fboundp 'consult-yank-pop) #'consult-yank-pop) ; HACK: see @ymarco's comment on #5013 ((fboundp 'counsel-yank-pop) #'counsel-yank-pop) ((fboundp 'helm-show-kill-ring) #'helm-show-kill-ring) ((error "No kill-ring search backend available. Enable ivy, helm or vertico!"))))) diff --git a/modules/config/default/config.el b/modules/config/default/config.el index 325ae1096..5ff8015e6 100644 --- a/modules/config/default/config.el +++ b/modules/config/default/config.el @@ -251,7 +251,7 @@ python-mode-map) (kbd "DEL") nil)) ;; Interferes with the def snippet in doom-snippets - ;; TODO Fix this upstream, in doom-snippets, instead + ;; TODO: Fix this upstream, in doom-snippets, instead (setq sp-python-insert-colon-in-function-definitions nil)))) @@ -273,16 +273,15 @@ ;; e) do none of this when inside a string (advice-add #'delete-backward-char :override #'+default--delete-backward-char-a) -;; HACK Makes `newline-and-indent' continue comments (and more reliably). -;; Consults `doom-point-in-comment-p' to detect a commented region and uses -;; that mode's `comment-line-break-function' to continue comments. If -;; neither exists, it will fall back to the normal behavior of -;; `newline-and-indent'. +;; HACK: Makes `newline-and-indent' continue comments (and more reliably). +;; Consults `doom-point-in-comment-p' to detect a commented region and uses +;; that mode's `comment-line-break-function' to continue comments. If neither +;; exists, it will fall back to the normal behavior of `newline-and-indent'. ;; -;; We use an advice here instead of a remapping because many modes define -;; and remap to their own newline-and-indent commands, and tackling all -;; those cases was judged to be more work than dealing with the edge cases -;; on a case by case basis. +;; We use an advice here instead of a remapping because many modes define and +;; remap to their own newline-and-indent commands, and tackling all those +;; cases was judged to be more work than dealing with the edge cases on a case +;; by case basis. (defadvice! +default--newline-indent-and-continue-comments-a (&rest _) "A replacement for `newline-and-indent'. Continues comments if executed from a commented line." diff --git a/modules/config/use-package/init.el b/modules/config/use-package/init.el index 8bb0cd084..78c01a773 100644 --- a/modules/config/use-package/init.el +++ b/modules/config/use-package/init.el @@ -52,9 +52,9 @@ (defun use-package-handler/:magic-minor (name _ arg rest state) (use-package-handle-mode name 'auto-minor-mode-magic-alist arg rest state)) - ;; HACK Fix `:load-path' so it resolves relative paths to the containing file, - ;; rather than `user-emacs-directory'. This is a done as a convenience - ;; for users, wanting to specify a local directory. + ;; HACK: Fix `:load-path' so it resolves relative paths to the containing + ;; file, rather than `user-emacs-directory'. This is a done as a convenience + ;; for users, wanting to specify a local directory. (defadvice! doom--resolve-load-path-from-containg-file-a (fn label arg &optional recursed) "Resolve :load-path from the current directory." :around #'use-package-normalize-paths diff --git a/modules/editor/evil/+commands.el b/modules/editor/evil/+commands.el index 4b0bf48d4..2196ade21 100644 --- a/modules/editor/evil/+commands.el +++ b/modules/editor/evil/+commands.el @@ -3,7 +3,7 @@ ;; ;;; Custom commands ;; Editing -(evil-ex-define-cmd "@" #'+evil:macro-on-all-lines) ; TODO Test me +(evil-ex-define-cmd "@" #'+evil:macro-on-all-lines) (evil-ex-define-cmd "R[ead]" #'+evil:read) (evil-ex-define-cmd "al[ign]" #'+evil:align) (evil-ex-define-cmd "ral[ign]" #'+evil:align-right) @@ -17,16 +17,16 @@ (evil-ex-define-cmd "l[ine]diff" #'evil-quick-diff) ;;; External resources -;; TODO (evil-ex-define-cmd "db" #'doom:db) -;; TODO (evil-ex-define-cmd "dbu[se]" #'doom:db-select) -;; TODO (evil-ex-define-cmd "go[ogle]" #'doom:google-search) +;; TODO: (evil-ex-define-cmd "db" #'doom:db) +;; TODO: (evil-ex-define-cmd "dbu[se]" #'doom:db-select) +;; TODO: (evil-ex-define-cmd "go[ogle]" #'doom:google-search) (evil-ex-define-cmd "lo[okup]" #'+lookup:online) (evil-ex-define-cmd "dash" #'+lookup:dash) (evil-ex-define-cmd "http" #'httpd-start) ; start http server (evil-ex-define-cmd "repl" #'+eval:repl) ; invoke or send to repl (evil-ex-define-cmd "h[elp]" #'+evil:help) -;; TODO (evil-ex-define-cmd "rx" 'doom:regex) ; open re-builder +;; TODO: (evil-ex-define-cmd "rx" 'doom:regex) ; open re-builder (evil-ex-define-cmd "sh[ell]" #'+eshell:run) (evil-ex-define-cmd "pad" #'+evil:open-scratch-buffer) diff --git a/modules/editor/evil/autoload/advice.el b/modules/editor/evil/autoload/advice.el index 7d7a0b1b1..0685d7396 100644 --- a/modules/editor/evil/autoload/advice.el +++ b/modules/editor/evil/autoload/advice.el @@ -85,7 +85,7 @@ more information on modifiers." (setq evil-auto-indent nil) (goto-char pos) (let ((ws (abs (skip-chars-backward " \t")))) - ;; FIXME oh god why + ;; REVIEW: There must be a better way... (save-excursion (if comment-line-break-function (funcall comment-line-break-function nil) @@ -107,7 +107,7 @@ more information on modifiers." (if comment-line-break-function (funcall comment-line-break-function nil) (comment-indent-new-line))) - ;; TODO Find a better way to do this + ;; TODO: Find a better way to do this ((and (eq major-mode 'haskell-mode) (fboundp 'haskell-indentation-newline-and-indent)) (setq evil-auto-indent nil) diff --git a/modules/editor/evil/autoload/unimpaired.el b/modules/editor/evil/autoload/unimpaired.el index 04100f35c..31027df36 100644 --- a/modules/editor/evil/autoload/unimpaired.el +++ b/modules/editor/evil/autoload/unimpaired.el @@ -35,7 +35,7 @@ By default, this only recognizes C preproc directives. To change this see `+evil-preprocessor-regexp'." (interactive "p") - ;; TODO More generalized search, to support directives in other languages? + ;; TODO: More generalized search, to support directives in other languages? (if (re-search-forward +evil-preprocessor-regexp nil t count) (goto-char (match-beginning 0)) (user-error "No preprocessor directives %s point" @@ -140,7 +140,7 @@ See `+evil/next-preproc-directive' for details." ;; ;;; Encoding/Decoding -;; NOTE For ]x / [x see :lang web +;; NOTE: For ]x / [x see :lang web ;; - `+web:encode-html-entities' ;; - `+web:decode-html-entities' diff --git a/modules/editor/file-templates/config.el b/modules/editor/file-templates/config.el index 2d95a6d6a..64ca3ef72 100644 --- a/modules/editor/file-templates/config.el +++ b/modules/editor/file-templates/config.el @@ -91,8 +91,8 @@ don't have a :trigger property in `+file-templates-alist'.") ("\\.class\\.php$" :trigger "__.class.php" :mode php-mode) (php-mode) ;; Python - ;; TODO ("tests?/test_.+\\.py$" :trigger "__" :mode nose-mode) - ;; TODO ("/setup\\.py$" :trigger "__setup.py" :mode python-mode) + ;; TODO: ("tests?/test_.+\\.py$" :trigger "__" :mode nose-mode) + ;; TODO: ("/setup\\.py$" :trigger "__setup.py" :mode python-mode) (python-mode) ;; Ruby ("/lib/.+\\.rb$" :trigger "__module" :mode ruby-mode :project t) diff --git a/modules/editor/multiple-cursors/config.el b/modules/editor/multiple-cursors/config.el index 78c5d0ea1..7862938e9 100644 --- a/modules/editor/multiple-cursors/config.el +++ b/modules/editor/multiple-cursors/config.el @@ -53,7 +53,7 @@ (defvar evil-mc-key-map (make-sparse-keymap)) :config - ;; HACK evil-mc's design is bizarre. Its variables and hooks are lazy loaded + ;; HACK: evil-mc's design is bizarre. Its variables and hooks are lazy loaded ;; rather than declared at top-level, some hooks aren't defined or ;; documented, it's a bit initializer-function drunk, and its minor modes ;; are intended to be perpetually active -- even when no cursors are active @@ -73,7 +73,7 @@ (letf! ((#'evil-mc-initialize-vars #'ignore)) (apply fn args))) - ;; REVIEW This is tremendously slow on macos and windows for some reason. + ;; REVIEW: This is tremendously slow on macos and windows for some reason. (setq evil-mc-enable-bar-cursor (featurep :system 'linux)) (after! smartparens @@ -112,8 +112,8 @@ (or (cdr fn) #'evil-mc-execute-default-call-with-count)))))) - ;; HACK Allow these commands to be repeated by prefixing them with a numerical - ;; argument. See gabesoft/evil-mc#110 + ;; HACK: Allow these commands to be repeated by prefixing them with a + ;; numerical argument. See gabesoft/evil-mc#110 (defadvice! +multiple-cursors--make-repeatable-a (fn) :around '(evil-mc-make-and-goto-first-cursor evil-mc-make-and-goto-last-cursor @@ -165,7 +165,7 @@ ;; Can't use `mc/cmds-to-run-once' because mc-lists.el overwrites it (add-to-list 'mc--default-cmds-to-run-once 'swiper-mc) - ;; TODO multiple-cursors config for Emacs users? + ;; TODO: multiple-cursors config for Emacs users? ;; mc doesn't play well with evil, this attempts to assuage some of its ;; problems so that any plugins that depend on multiple-cursors (which I have diff --git a/modules/editor/snippets/config.el b/modules/editor/snippets/config.el index 1346c5dc4..35b88478c 100644 --- a/modules/editor/snippets/config.el +++ b/modules/editor/snippets/config.el @@ -40,8 +40,8 @@ (add-to-list 'load-path +snippets-dir) (require 'doom-snippets nil t) - ;; HACK In case `+snippets-dir' and `doom-snippets-dir' are the same, or - ;; duplicates exist in `yas-snippet-dirs'. + ;; HACK: In case `+snippets-dir' and `doom-snippets-dir' are the same, or + ;; duplicates exist in `yas-snippet-dirs'. (advice-add #'yas-snippet-dirs :filter-return #'delete-dups) ;; Remove GUI dropdown prompt (prefer ivy/helm) @@ -85,14 +85,14 @@ (:map snippet-mode-map "C-c C-k" #'+snippet--abort)) - ;; REVIEW Fix #2639: For some reason `yas--all-templates' returns duplicates - ;; of some templates. Until I figure out the real cause this fixes it. + ;; REVIEW: Fix #2639: For some reason `yas--all-templates' returns duplicates + ;; of some templates. Until I figure out the real cause this fixes it. (defadvice! +snippets--remove-duplicates-a (templates) :filter-return #'yas--all-templates (cl-delete-duplicates templates :test #'equal)) - ;; HACK Smartparens will interfere with snippets expanded by `hippie-expand`, - ;; so temporarily disable smartparens during snippet expansion. + ;; HACK: Smartparens will interfere with snippets expanded by `hippie-expand`, + ;; so temporarily disable smartparens during snippet expansion. (after! hippie-exp (defvar +snippets--smartparens-enabled-p t) (defvar +snippets--expanding-p nil) diff --git a/modules/emacs/eww/autoload.el b/modules/emacs/eww/autoload.el index 7a7d00c48..fc25d02f7 100644 --- a/modules/emacs/eww/autoload.el +++ b/modules/emacs/eww/autoload.el @@ -20,7 +20,7 @@ too, so strings take the form: \"POSITION ~ LABEL @ URL\"." (url (when (stringp raw-url) (propertize raw-url 'face 'link))) (label (replace-regexp-in-string - "\n" " " ; NOTE 2021-07-25: newlines break completion + "\n" " " ; 2021-07-25: newlines break completion (buffer-substring-no-properties start-point-prop end-point-prop))) (point start-point-prop) @@ -47,7 +47,7 @@ too, so strings take the form: \"POSITION ~ LABEL @ URL\"." (start-point-prop (prop-match-beginning match)) (end-point-prop (prop-match-end match)) (text (replace-regexp-in-string - "\n" " " ; NOTE 2021-07-25: newlines break completion + "\n" " " ; 2021-07-25: newlines break completion (buffer-substring-no-properties start-point-prop end-point-prop)))) (cond diff --git a/modules/emacs/undo/config.el b/modules/emacs/undo/config.el index d42ea7da1..cc06e8f63 100644 --- a/modules/emacs/undo/config.el +++ b/modules/emacs/undo/config.el @@ -36,11 +36,11 @@ ;; is our priority within Emacs (setq undo-fu-session-compression 'zst)) - ;; HACK Fix #4993: we've advised `make-backup-file-name-1' to produced SHA1'ed - ;; filenames to prevent file paths that are too long, so we force - ;; `undo-fu-session--make-file-name' to use it instead of its own - ;; home-grown overly-long-filename generator. - ;; TODO PR this upstream; should be a universal issue + ;; HACK: Fix #4993: we've advised `make-backup-file-name-1' to produced + ;; SHA1'ed filenames to prevent file paths that are too long, so we force + ;; `undo-fu-session--make-file-name' to use it instead of its own home-grown + ;; overly-long-filename generator. + ;; TODO: PR this upstream; should be a universal issue (defadvice! +undo-fu-make-hashed-session-file-name-a (file) :override #'undo-fu-session--make-file-name (concat (let ((backup-directory-alist `(("." . ,undo-fu-session-directory)))) diff --git a/modules/emacs/vc/autoload/bug-reference-backport.el b/modules/emacs/vc/autoload/bug-reference-backport.el index 4b58b8701..eb01325c2 100644 --- a/modules/emacs/vc/autoload/bug-reference-backport.el +++ b/modules/emacs/vc/autoload/bug-reference-backport.el @@ -1,6 +1,6 @@ ;;; emacs/vc/autoload/bug-reference-backport.el -*- lexical-binding: t; -*- ;;;###if (< emacs-major-version 28) -;; DEPRECATED Remove when Emacs 27.x support is dropped +;; DEPRECATED: Remove when Emacs 27.x support is dropped ;; In Emacs 28, the built-in bug-reference package started consulting vc for ;; repo information (to inform its bug reference URLs). This incredibly useful diff --git a/modules/emacs/vc/config.el b/modules/emacs/vc/config.el index 3414c462b..6e7830173 100644 --- a/modules/emacs/vc/config.el +++ b/modules/emacs/vc/config.el @@ -88,7 +88,7 @@ ;; `header-line-format', which has better visibility. (setq git-timemachine-show-minibuffer-details t) - ;; TODO PR this to `git-timemachine' + ;; REVIEW: PR this to `git-timemachine' (defadvice! +vc-support-git-timemachine-a (fn) "Allow `browse-at-remote' commands in git-timemachine buffers to open that file in your browser at the visited revision." @@ -159,17 +159,15 @@ info in the `header-line-format' is a more visible indicator." ;; using commit hashes rather than branch names. (setq browse-at-remote-prefer-symbolic nil) - ;; Add codeberg.org support - ;; TODO: PR this upstream? + ;; Expand recognition for more forges (like self-hosted gitlab.* subdomains + ;; and codeberg). + ;; REVIEW: PR these upstream? (add-to-list 'browse-at-remote-remote-type-regexps '(:host "^codeberg\\.org$" :type "codeberg")) - ;; Expand recognition for gitlab hosts besides gitlab.org or gitlab.gnome.org - ;; which are presumably hosted in a gitlab.* subdomain. - ;; TODO: PR this upstream? (add-to-list 'browse-at-remote-remote-type-regexps '(:host "^gitlab\\." :type "gitlab") 'append) - ;; HACK `browse-at-remote' produces urls with `nil' in them, when the repo is - ;; detached. This creates broken links. I think it is more sensible to - ;; fall back to master in those cases. + ;; HACK: `browse-at-remote' produces urls with `nil' in them, when the repo is + ;; detached. This creates broken links. I think it is more sensible to fall + ;; back to master in those cases. (defadvice! +vc--fallback-to-master-branch-a () "Return 'master' in detached state." :after-until #'browse-at-remote--get-local-branch diff --git a/modules/email/mu4e/autoload/email.el b/modules/email/mu4e/autoload/email.el index a52afe08e..c9caf70eb 100644 --- a/modules/email/mu4e/autoload/email.el +++ b/modules/email/mu4e/autoload/email.el @@ -100,7 +100,7 @@ default/fallback account." (defun +mu4e/compose () "Compose a new email." (interactive) - ;; TODO Interactively select email account + ;; TODO: Interactively select email account (call-interactively #'mu4e-compose-new)) (defun +mu4e--get-string-width (str) @@ -279,7 +279,7 @@ attach a file, or select a folder to open dired in and select file attachments (using `dired-mu4e-attach-ctrl-c-ctrl-c'). When otherwise called, open a dired buffer and enable `dired-mu4e-attach-ctrl-c-ctrl-c'." - ;; TODO add ability to attach files (+dirs) as a single (named) archive + ;; TODO: add ability to attach files (+dirs) as a single (named) archive (interactive "p") (pcase major-mode ((or 'mu4e-compose-mode 'org-msg-edit-mode) diff --git a/modules/email/mu4e/config.el b/modules/email/mu4e/config.el index 9040a1517..6b31994fe 100644 --- a/modules/email/mu4e/config.el +++ b/modules/email/mu4e/config.el @@ -180,7 +180,7 @@ is non-nil." (add-to-list 'mu4e-bookmarks '("flag:flagged" "Flagged messages" ?f) t) - ;; TODO avoid assuming that nerd-icons is present + ;; TODO: avoid assuming that nerd-icons is present (defvar +mu4e-header-colorized-faces '(nerd-icons-green nerd-icons-lblue @@ -598,7 +598,7 @@ See `+mu4e-msg-gmail-p' and `mu4e-sent-messages-behavior'.") ;; don't save message to Sent Messages, Gmail/IMAP takes care of this (setq mu4e-sent-messages-behavior - (lambda () ;; TODO make use +mu4e-msg-gmail-p + (lambda () ;; TODO: make use +mu4e-msg-gmail-p (if (or (string-match-p "@gmail.com\\'" (message-sendmail-envelope-from)) (member (message-sendmail-envelope-from) (mapcar #'car +mu4e-gmail-accounts))) diff --git a/modules/email/notmuch/autoload.el b/modules/email/notmuch/autoload.el index bad85b927..1cf1a6533 100644 --- a/modules/email/notmuch/autoload.el +++ b/modules/email/notmuch/autoload.el @@ -42,7 +42,7 @@ (`gmi (concat "cd " +notmuch-mail-folder " && gmi sync && notmuch new")) ((or `mbsync - `mbsync-xdg) ; DEPRECATED `mbsync-xdg' is now just `mbsync' + `mbsync-xdg) ; DEPRECATED: `mbsync-xdg' is now just `mbsync' (format "mbsync %s -a && notmuch new" (if-let* ((config-file (doom-glob (or (getenv "XDG_CONFIG_HOME") diff --git a/modules/email/notmuch/config.el b/modules/email/notmuch/config.el index e6eafd317..9c2bd4e4c 100644 --- a/modules/email/notmuch/config.el +++ b/modules/email/notmuch/config.el @@ -1,7 +1,5 @@ ;;; email/notmuch/config.el -*- lexical-binding: t; -*- -;; FIXME This module is a WIP! - (defvar +notmuch-home-function #'notmuch "Function for customizing the landing page for doom-emacs =notmuch.") diff --git a/modules/email/wanderlust/packages.el b/modules/email/wanderlust/packages.el index 1c8205dae..bb2d06cfe 100644 --- a/modules/email/wanderlust/packages.el +++ b/modules/email/wanderlust/packages.el @@ -1,9 +1,9 @@ ;; -*- no-byte-compile: t; -*- ;;; app/wanderlust/packages.el -;; HACK These are wanderlust's dependencies (wanderlust depends on semi, semi -;; depends on flim, flim on apel), but they all have non-standard default -;; branches which straight cannot detect without our help. +;; HACK: These are wanderlust's dependencies (wanderlust depends on semi, semi +;; depends on flim, flim on apel), but they all have non-standard default +;; branches which straight cannot detect without our help. (package! apel :recipe (:host github :repo "wanderlust/apel" :branch "apel-wl") :pin "2383abfd3a27c094ae9095b05103167cf810379b") diff --git a/modules/input/layout/+bepo.el b/modules/input/layout/+bepo.el index 549e553fc..990e61783 100644 --- a/modules/input/layout/+bepo.el +++ b/modules/input/layout/+bepo.el @@ -11,8 +11,8 @@ If 'strict, the module does a normal swap and 'c' bindings go to 'h', 'r' bindin In all cases, 'h' functions go to 'c' and 'l' ones go to 'r' so the navigation keys still feel vim-like.") ;; Highlight non breaking spaces as error in prog modes only -;; REVIEW `nobreak-char-display' is defined in xdisp.c; will that work in non-X -;; builds? From early observations in sway+pgtk, it does not. +;; REVIEW: `nobreak-char-display' is defined in xdisp.c; will that work in non-X +;; builds? From early observations in sway+pgtk, it does not. (setq nobreak-char-display t) (set-face-attribute 'nobreak-space nil :underline t) @@ -20,8 +20,8 @@ In all cases, 'h' functions go to 'c' and 'l' ones go to 'r' so the navigation k ;; ;;; Initializers -;; TODO Separate each package into their own hook, so users can -;; enable/disable/add their own per-package remappings. +;; TODO: Separate each package into their own hook, so users can +;; enable/disable/add their own per-package remappings. (defun +layout-remap-keys-for-bepo-h () (setq avy-keys '(?a ?u ?i ?e ?, ?c ?t ?s ?r ?n) diff --git a/modules/lang/cc/config.el b/modules/lang/cc/config.el index 79d21831b..066d7aa70 100644 --- a/modules/lang/cc/config.el +++ b/modules/lang/cc/config.el @@ -76,9 +76,9 @@ This is ignored by ccls.") (add-to-list 'find-sibling-rules '("/\\([^/]+\\)\\.c\\(c\\|pp\\)?\\'" "\\1.h\\(h\\|pp\\)?\\'")) (add-to-list 'find-sibling-rules '("/\\([^/]+\\)\\.h\\(h\\|pp\\)?\\'" "\\1.c\\(c\\|pp\\)?\\'")) - ;; HACK Suppress 'Args out of range' error in when multiple modifications are - ;; performed at once in a `c++-mode' buffer, e.g. with `iedit' or - ;; multiple cursors. + ;; HACK: Suppress 'Args out of range' error in when multiple modifications are + ;; performed at once in a `c++-mode' buffer, e.g. with `iedit' or multiple + ;; cursors. (undefadvice! +cc--suppress-silly-errors-a (fn &rest args) :around #'c-after-change-mark-abnormal-strings (ignore-errors (apply fn args))) @@ -205,7 +205,6 @@ This is ignored by ccls.") :map c++-mode-map :desc "Show type inheritance hierarchy" "ct" #'+cc/eglot-ccls-inheritance-hierarchy) - ;; NOTE : This setting is untested yet (after! eglot (when (featurep :system 'macos) (add-to-list 'eglot-workspace-configuration diff --git a/modules/lang/clojure/autoload.el b/modules/lang/clojure/autoload.el index b3bc4beef..47d636819 100644 --- a/modules/lang/clojure/autoload.el +++ b/modules/lang/clojure/autoload.el @@ -16,7 +16,7 @@ at point." (defun +clojure/open-repl (&optional arg type) "Open a Cider REPL for clojure and return the buffer." (interactive "P") - ;; TODO Better error handling + ;; TODO: Better error handling. ;; type is `clj' for clojure and `cljs' for clojurescript ;; ... with no type specified, assume `clj'. (let ((type (or type 'clj))) diff --git a/modules/lang/clojure/config.el b/modules/lang/clojure/config.el index 54d2ca973..99068d11e 100644 --- a/modules/lang/clojure/config.el +++ b/modules/lang/clojure/config.el @@ -88,7 +88,7 @@ ;; library being loaded only when is absolutely needed, which is too late for ;; reconfiguration in many cases. (use-package! cider-mode - ;; NOTE if `org-directory' doesn't exist, `cider-jack' in won't work + ;; NOTE: If `org-directory' doesn't exist, `cider-jack' in won't work :hook (clojure-mode-local-vars . cider-mode) :hook (clojurec-mode-local-vars . cider-mode) :hook (clojurescript-mode-local-vars . cider-mode) @@ -105,7 +105,7 @@ clojurec-mode clojure-ts-clojurec-mode) #'cider-eval-region)) - ;; HACK Fix radian-software/radian#446: CIDER tries to calculate the frame's + ;; HACK: Fix radian-software/radian#446: CIDER tries to calculate the frame's ;; background too early; sometimes before the initial frame has been ;; initialized, causing errors. (defvar cider-docview-code-background-color nil) diff --git a/modules/lang/clojure/packages.el b/modules/lang/clojure/packages.el index 7cad1aef8..e46f22dea 100644 --- a/modules/lang/clojure/packages.el +++ b/modules/lang/clojure/packages.el @@ -1,15 +1,15 @@ ;; -*- no-byte-compile: t; -*- ;;; lang/clojure/packages.el -;; HACK Fix #5577. Paredit is a cider dependency. We install paredit ourselves -;; to get it from emacsmirror, because the original upstream is a custom -;; git server with shallow clones disabled. +;; HACK: Fix #5577. Paredit is a cider dependency. We install paredit ourselves +;; to get it from emacsmirror, because the original upstream is a custom git +;; server with shallow clones disabled. (package! paredit :recipe (:host github :repo "emacsmirror/paredit") :pin "af075775af91f2dbc63b915d762b4aec092946c4") -;; HACK Forward declare these clj-refactor/cider deps so that their deps are -;; byte-compiled first. +;; HACK: Forward declare these clj-refactor/cider deps so that their deps are +;; byte-compiled first. (package! parseclj :pin "6af22372e0fe14df882dd300b22b12ba2d7e00b0") (package! parseedn :pin "3407e4530a367b6c2b857dae261cdbb67a440aaa") diff --git a/modules/lang/common-lisp/autoload/common-lisp.el b/modules/lang/common-lisp/autoload/common-lisp.el index b40de3e51..5bd5f56de 100644 --- a/modules/lang/common-lisp/autoload/common-lisp.el +++ b/modules/lang/common-lisp/autoload/common-lisp.el @@ -1,7 +1,7 @@ ;;; lang/common-lisp/autoload/common-lisp.el -*- lexical-binding: t; -*- -;; HACK Fix #1772: void-variable sly-contribs errors due to sly packages (like -;; `sly-macrostep') trying to add to `sly-contribs' before it is defined. +;; HACK: Fix #1772: void-variable sly-contribs errors due to sly packages (like +;; `sly-macrostep') trying to add to `sly-contribs' before it is defined. ;;;###autoload (defvar sly-contribs '(sly-fancy)) ;;;###autoload diff --git a/modules/lang/common-lisp/config.el b/modules/lang/common-lisp/config.el index f85cdc146..91685b46e 100644 --- a/modules/lang/common-lisp/config.el +++ b/modules/lang/common-lisp/config.el @@ -37,9 +37,9 @@ ;; This needs to be appended so it fires later than `sly-editing-mode' (add-hook 'lisp-mode-local-vars-hook #'sly-lisp-indent-compatibility-mode 'append) - ;; HACK Ensures that sly's contrib modules are loaded as soon as possible, but - ;; also as late as possible, so users have an opportunity to override - ;; `sly-contrib' in an `after!' block. + ;; HACK: Ensures that sly's contrib modules are loaded as soon as possible, + ;; but also as late as possible, so users have an opportunity to override + ;; `sly-contrib' in an `after!' block. (add-hook! 'after-init-hook (after! sly (sly-setup))) :config diff --git a/modules/lang/coq/config.el b/modules/lang/coq/config.el index 3398b257c..9f0ee2656 100644 --- a/modules/lang/coq/config.el +++ b/modules/lang/coq/config.el @@ -13,8 +13,8 @@ ;; Doom syncs other indent variables with `tab-width'; we trust major modes to ;; set it -- which most of them do -- but coq-mode doesn't, so... tab-width proof-indent - ;; HACK Fix #2081: Doom continues comments on RET, but coq-mode doesn't have a - ;; sane `comment-line-break-function', so... + ;; HACK: Fix #2081: Doom continues comments on RET, but coq-mode doesn't have + ;; a sane `comment-line-break-function', so... comment-line-break-function nil) ;; We've replaced coq-mode abbrevs with yasnippet snippets (in the snippets diff --git a/modules/lang/emacs-lisp/autoload/emacs-lisp.el b/modules/lang/emacs-lisp/autoload/emacs-lisp.el index 9c8ac2aa2..e16f05143 100644 --- a/modules/lang/emacs-lisp/autoload/emacs-lisp.el +++ b/modules/lang/emacs-lisp/autoload/emacs-lisp.el @@ -148,7 +148,7 @@ if it's callable, `apropos' otherwise." #'helpful-at-point #'describe-symbol))))) -;; DEPRECATED Remove when 28 support is dropped. +;; DEPRECATED: Remove when 28 support is dropped. (unless (fboundp 'lisp--local-defform-body-p) (fset 'lisp--local-defform-body-p #'ignore)) @@ -534,7 +534,7 @@ Adapted from URL `https://www.reddit.com/r/emacs/comments/d7x7x8/finally_fixing_ (ignore-errors (or (save-excursion (goto-char first) - ;; FIXME Can we avoid `syntax-ppss'? + ;; FIXME: Can we avoid `syntax-ppss'? (when-let* ((parse-sexp-ignore-comments t) (end (scan-lists (point) 1 0)) (depth (ppss-depth (syntax-ppss)))) diff --git a/modules/lang/ess/config.el b/modules/lang/ess/config.el index d58c5bee7..87341b056 100644 --- a/modules/lang/ess/config.el +++ b/modules/lang/ess/config.el @@ -37,8 +37,8 @@ '(company-R-args company-R-objects company-dabbrev-code :separate)) (setq-hook! 'ess-r-mode-hook - ;; HACK Fix #2233: Doom continues comments on RET, but ess-r-mode doesn't - ;; have a sane `comment-line-break-function', so... + ;; HACK: Fix #2233: Doom continues comments on RET, but ess-r-mode doesn't + ;; have a sane `comment-line-break-function', so... comment-line-break-function nil) ;; HACK: make the REPL buffer more responsive. diff --git a/modules/lang/faust/config.el b/modules/lang/faust/config.el index 5f49a4321..9a21b2351 100644 --- a/modules/lang/faust/config.el +++ b/modules/lang/faust/config.el @@ -5,9 +5,9 @@ :config (set-company-backend! '(faust-mode faustine-mode) '(company-dabbrev-code +faust-company-backend company-yasnippet)) - ;; HACK Both `faust-mode' and `faustine-mode' are hardcoded to use - ;; auto-complete. This silences the obnoxious 'You really should install and - ;; use auto-complete' warnings when starting them. + ;; HACK: Both `faust-mode' and `faustine-mode' are hardcoded to use + ;; auto-complete. This silences the obnoxious 'You really should install and + ;; use auto-complete' warnings when starting them. (defvar ac-modes nil) (defvar ac-sources nil) diff --git a/modules/lang/julia/config.el b/modules/lang/julia/config.el index 99850f6f1..870ec9d43 100644 --- a/modules/lang/julia/config.el +++ b/modules/lang/julia/config.el @@ -122,7 +122,7 @@ (after! julia-mode (set-repl-handler! 'julia-mode #'+julia/open-snail-repl :persist t - ;; FIXME These aren't working as expected + ;; FIXME: These aren't working as expected :send-region #'julia-snail-send-region :send-buffer #'julia-snail-send-buffer-file)) diff --git a/modules/lang/julia/doctor.el b/modules/lang/julia/doctor.el index 547f9f7c2..e3243bf0b 100644 --- a/modules/lang/julia/doctor.el +++ b/modules/lang/julia/doctor.el @@ -22,4 +22,4 @@ (unless (zerop (car (apply #'doom-call-process args))) (warn! "Couldn't find LanguageServer.jl and/or SymbolServer.jl")))) -;; TODO Check for snail +;; TODO: Check for snail diff --git a/modules/lang/nim/config.el b/modules/lang/nim/config.el index 70fe70ad1..0ab5b4ea5 100644 --- a/modules/lang/nim/config.el +++ b/modules/lang/nim/config.el @@ -15,7 +15,7 @@ nimsuggest isn't installed." (set-formatter! 'nmfmt '("nimpretty" filepath) :modes '(nim-mode)) (when (featurep :system 'windows) - ;; TODO File PR/report upstream (https://github.com/nim-lang/nim-mode) + ;; TODO: File PR/report upstream (https://github.com/nim-lang/nim-mode) (defadvice! +nim--suggest-get-temp-file-name-a (path) "Removes invalid characters from the temp file path, including the unicode character that colon is replaced with, which is known to cause issues on diff --git a/modules/lang/nix/autoload.el b/modules/lang/nix/autoload.el index a8b2076b9..9bc90d5e7 100644 --- a/modules/lang/nix/autoload.el +++ b/modules/lang/nix/autoload.el @@ -17,7 +17,7 @@ "Look up documentation on a nix option." (interactive (list - ;; REVIEW Must be a better way to do this + ;; REVIEW: Must be a better way to do this (when (and (looking-at-p "[a-zA-Z0-9-_\\.]") (not (doom-point-in-string-or-comment-p))) (buffer-substring-no-properties @@ -30,8 +30,8 @@ (require 'nixos-options) (cond ((modulep! :completion helm) (require 'helm-nixos-options) - ;; REVIEW We reimplment `helm-nixos-options' so we can supply - ;; `initial-input'. Maybe use `helm-attrset' instead? + ;; REVIEW: We reimplment `helm-nixos-options' so we can supply + ;; `initial-input'. Maybe use `helm-attrset' instead? (helm :sources `(,(helm-source-nixos-options-search)) :buffer "*helm-nixos-options*" :input initial-input)) @@ -74,7 +74,7 @@ (prog1 (set-auto-mode-0 mode) (when (eq major-mode 'sh-mode) (sh-set-shell interp)) - ;; HACK Without this, quickrun tries to evaluate code directly - ;; with (cached)?nix-shell. - ;; TODO Use the nix-shell/cached-nix-shell-given interpreter + ;; HACK: Without this, quickrun tries to evaluate code directly + ;; with (cached)?nix-shell. + ;; TODO: Use the nix-shell/cached-nix-shell-given interpreter (setq-local quickrun-option-shebang nil)))))))) diff --git a/modules/lang/org/autoload/org-refile.el b/modules/lang/org/autoload/org-refile.el index 87365aa39..2f29b7948 100644 --- a/modules/lang/org/autoload/org-refile.el +++ b/modules/lang/org/autoload/org-refile.el @@ -1,6 +1,6 @@ ;;; lang/org/autoload/org-refile.el -*- lexical-binding: t; -*- -;; REVIEW These are all proof-of-concept. Refactor me! +;; REVIEW: These are all proof-of-concept. Refactor me! ;;;###autoload (defun +org/refile-to-current-file (arg &optional file) diff --git a/modules/lang/org/autoload/org.el b/modules/lang/org/autoload/org.el index 901a3148b..35a213b30 100644 --- a/modules/lang/org/autoload/org.el +++ b/modules/lang/org/autoload/org.el @@ -345,7 +345,7 @@ Otherwise, falls back to `org-fill-paragraph' to reflow paragraphs." (interactive) (let ((element (org-element-at-point))) (cond ((doom-region-active-p) - ;; TODO Perform additional formatting? + ;; TODO: Perform additional formatting? ;; (save-restriction ;; (narrow-to-region beg end) ;; (org-table-recalculate t) diff --git a/modules/lang/org/config.el b/modules/lang/org/config.el index 72e1d04b8..0dae45e98 100644 --- a/modules/lang/org/config.el +++ b/modules/lang/org/config.el @@ -140,9 +140,12 @@ Is relative to `org-directory', unless it is absolute. Is used in Doom's default (plist-put org-format-latex-options :scale 1.5) ; larger previews - ;; HACK Face specs fed directly to `org-todo-keyword-faces' don't respect - ;; underlying faces like the `org-todo' face does, so we define our own - ;; intermediary faces that extend from org-todo. + ;; HACK: Face specs fed directly to `org-todo-keyword-faces' don't respect + ;; underlying faces like the `org-todo' face does, so we define our own + ;; intermediary faces that extend from org-todo. + ;; REVIEW: On one hand, this config is too opinionated, on the other, these + ;; are the most commonly reconfigured variables in Org so they don't step on + ;; many toes. Consider either removing or simplifying this! (with-no-warnings (custom-declare-face '+org-todo-active '((t (:inherit (bold font-lock-constant-face org-todo)))) "") (custom-declare-face '+org-todo-project '((t (:inherit (bold font-lock-doc-face org-todo)))) "") @@ -407,8 +410,8 @@ I like: (when (bound-and-true-p org-capture-is-refiling) (save-buffer)))) - ;; HACK Doom doesn't support `customize'. Best not to advertise it as an - ;; option in `org-capture's menu. + ;; HACK: Doom doesn't support `customize'. Best not to advertise it as an + ;; option in `org-capture's menu. (defadvice! +org--remove-customize-option-a (fn table title &optional prompt specials) :around #'org-mks (funcall fn table title prompt @@ -1066,9 +1069,9 @@ between the two." #'+org-link-doom--help-echo-from-textprop) (+org-link-doom--help-echo-from-textprop nil (current-buffer) (point))))) - ;; HACK Fix #2972: infinite recursion when eldoc kicks in 'org' or 'python' + ;; HACK: Fix #2972: infinite recursion when eldoc kicks in 'org' or 'python' ;; src blocks. - ;; TODO Should be reported upstream! + ;; REVIEW: Should be reported upstream! (puthash "org" #'ignore org-eldoc-local-functions-cache) (puthash "plantuml" #'ignore org-eldoc-local-functions-cache) (puthash "python" #'python-eldoc-function org-eldoc-local-functions-cache)) @@ -1300,16 +1303,16 @@ between the two." ;; Other org properties are all-caps. Be consistent. (setq org-effort-property "EFFORT") - ;; HACK `org-id' doesn't check if `org-id-locations-file' exists or is - ;; writeable before trying to read/write to it, potentially throwing a - ;; file-error if it doesn't, which can leave Org in a broken state. + ;; HACK: `org-id' doesn't check if `org-id-locations-file' exists or is + ;; writeable before trying to read/write to it, potentially throwing a + ;; file-error if it doesn't, which can leave Org in a broken state. (defadvice! +org--fail-gracefully-a (fn &rest args) :around '(org-id-locations-save org-id-locations-load) (with-demoted-errors "org-id-locations: %s" (apply fn args))) (add-hook 'org-open-at-point-functions #'doom-set-jump-h) - ;; HACK For functions that dodge `org-open-at-point-functions', like + ;; HACK: For functions that dodge `org-open-at-point-functions', like ;; `org-id-open', `org-goto', or roam: links. (advice-add #'org-mark-ring-push :around #'doom-set-jump-a) diff --git a/modules/lang/org/contrib/dragndrop.el b/modules/lang/org/contrib/dragndrop.el index 3562f12f7..5f1a7fea3 100644 --- a/modules/lang/org/contrib/dragndrop.el +++ b/modules/lang/org/contrib/dragndrop.el @@ -9,7 +9,7 @@ org-download-clipboard org-download-dnd-base64 :init - ;; HACK We add these manually so that org-download is truly lazy-loaded + ;; HACK: We add these manually so that org-download is truly lazy-loaded (add-to-list 'dnd-protocol-alist '("^data:" . org-download-dnd-base64)) (add-to-list 'dnd-protocol-alist '("^\\(?:https?\\|ftp\\|file\\|nfs\\):" . org-download-dnd)) (advice-add #'org-download-enable :override #'ignore) diff --git a/modules/lang/org/contrib/journal.el b/modules/lang/org/contrib/journal.el index 34fbaa254..ae43f82da 100644 --- a/modules/lang/org/contrib/journal.el +++ b/modules/lang/org/contrib/journal.el @@ -4,11 +4,11 @@ (use-package! org-journal :defer t :init - ;; HACK `org-journal' adds a `magic-mode-alist' entry for detecting journal - ;; files, but this causes us lazy loaders a big problem: an unacceptable - ;; delay on the first file the user opens, because calling the autoloaded - ;; `org-journal-is-journal' pulls all of `org' with it. So, we replace it - ;; with our own, extra layer of heuristics. + ;; HACK: `org-journal' adds a `magic-mode-alist' entry for detecting journal + ;; files, but this causes us lazy loaders a big problem: an unacceptable + ;; delay on the first file the user opens, because calling the autoloaded + ;; `org-journal-is-journal' pulls all of `org' with it. So, we replace it + ;; with our own, extra layer of heuristics. (add-to-list 'magic-mode-alist '(+org-journal-p . org-journal-mode)) (defun +org-journal-p () @@ -27,8 +27,9 @@ org-journal-cache-file (file-name-concat doom-profile-cache-dir "org-journal")) :config - ;; Remove the orginal journal file detector and rely on `+org-journal-p' - ;; instead, to avoid loading org-journal until the last possible moment. + ;; HACK: Remove the original journal file detector and rely on + ;; `+org-journal-p' instead, to avoid loading org-journal until the last + ;; possible moment. (setq magic-mode-alist (assq-delete-all 'org-journal-is-journal magic-mode-alist)) ;; `org-journal' can't deal with symlinks, so resolve them here. diff --git a/modules/lang/org/contrib/roam.el b/modules/lang/org/contrib/roam.el index 3216c8a50..025f0bdb8 100644 --- a/modules/lang/org/contrib/roam.el +++ b/modules/lang/org/contrib/roam.el @@ -75,7 +75,7 @@ inserting the link." (add-to-list 'org-roam-node-template-prefixes '("doom-tags" . "#")) (add-to-list 'org-roam-node-template-prefixes '("doom-type" . "@")) - ;; REVIEW Remove when addressed upstream. See org-roam/org-roam#2066. + ;; REVIEW: Remove when addressed upstream. See org-roam/org-roam#2066. (defadvice! +org--roam-fix-completion-width-for-vertico-a (fn &rest args) "Fixes completion candidate width for vertico users." :around #'org-roam-node-read--to-candidate @@ -109,7 +109,7 @@ inserting the link." (add-hook 'org-roam-mode-hook #'turn-on-visual-line-mode) ;; Use a 'roam:X' link's description if X is empty. - ;; TODO PR this upstream? + ;; REVIEW: PR this upstream? (advice-add #'org-roam-link-follow-link :filter-args #'org-roam-link-follow-link-with-description-a) (advice-add #'org-roam-link-replace-at-point :override #'org-roam-link-replace-at-point-a) diff --git a/modules/lang/org/packages.el b/modules/lang/org/packages.el index debf2ab68..4acdae64b 100644 --- a/modules/lang/org/packages.el +++ b/modules/lang/org/packages.el @@ -54,7 +54,7 @@ (package! toc-org :pin "6d3ae0fc47ce79b1ea06cabe21a3c596395409cd") (package! org-cliplink :pin "13e0940b65d22bec34e2de4bc8cba1412a7abfbc") -;; TODO Adjust when this is added to GNU ELPA +;; TODO: Adjust when this is added to GNU ELPA (when (modulep! +contacts) (package! org-contacts :recipe (:host github :repo "doomelpa/org-contacts") diff --git a/modules/lang/plantuml/autoload.el b/modules/lang/plantuml/autoload.el index 3d1e37aef..080b5cd82 100644 --- a/modules/lang/plantuml/autoload.el +++ b/modules/lang/plantuml/autoload.el @@ -5,7 +5,7 @@ "Execute a block of plantuml code with org-babel. This function is called by `org-babel-execute-src-block'." (require 'plantuml-mode) - ;; REVIEW Refactor me + ;; REVIEW: Refactor me (let* ((body (replace-regexp-in-string "^[[:blank:]\n]*\\(@start\\)" "\\1" diff --git a/modules/lang/python/config.el b/modules/lang/python/config.el index 4b34ae362..b78b8e2de 100644 --- a/modules/lang/python/config.el +++ b/modules/lang/python/config.el @@ -262,10 +262,10 @@ (use-package! pip-requirements :defer t :config - ;; HACK `pip-requirements-mode' performs a sudden HTTP request to + ;; HACK: `pip-requirements-mode' performs a sudden HTTP request to ;; https://pypi.org/simple, which causes unexpected hangs (see #5998). This ;; advice defers this behavior until the first time completion is invoked. - ;; REVIEW More sensible behavior should be PRed upstream. + ;; REVIEW: More sensible behavior should be PRed upstream. (defadvice! +python--init-completion-a (&rest args) "Call `pip-requirements-fetch-packages' first time completion is invoked." :before #'pip-requirements-complete-at-point diff --git a/modules/lang/rust/config.el b/modules/lang/rust/config.el index 43267a50c..feadc49dc 100644 --- a/modules/lang/rust/config.el +++ b/modules/lang/rust/config.el @@ -18,7 +18,7 @@ :mode ("\\.rs\\'" . rustic-mode) :defer t :preface - ;; HACK `rustic' sets up some things too early. I'd rather disable it and let + ;; HACK: `rustic' sets up some things too early. I'd rather disable it and let ;; our respective modules standardize how they're initialized. (setq rustic-lsp-client nil) (after! rustic-lsp @@ -33,7 +33,7 @@ `((rust :url "https://github.com/tree-sitter/tree-sitter-rust" :rev ,(if (< (treesit-library-abi-version) 15) "v0.23.2" "v0.24.0"))))) - ;; HACK Certainly, `rustic-babel' does this, but the package (and many other + ;; HACK: Certainly, `rustic-babel' does this, but the package (and many other ;; rustic packages) must be loaded in order for them to take effect. To lazy ;; load it all, it must be done earlier: (after! org-src @@ -88,7 +88,7 @@ (s-join " ")))) (lsp--render-element (concat "```rust\n" sig cmt "\n```"))))))) - ;; HACK If lsp/eglot isn't available, it attempts to install lsp-mode via + ;; HACK: If lsp/eglot isn't available, it attempts to install lsp-mode via ;; package.el. Doom manages its own dependencies through straight so disable ;; this behavior to avoid package-not-initialized errors. (defadvice! +rust--dont-install-packages-a (&rest _) diff --git a/modules/lang/scheme/autoload.el b/modules/lang/scheme/autoload.el index 75796492d..db930f2ba 100644 --- a/modules/lang/scheme/autoload.el +++ b/modules/lang/scheme/autoload.el @@ -12,10 +12,10 @@ property lists and names starting with 'default'." (goto-char (1+ (elt state 1))) (parse-partial-sexp (point) calculate-lisp-indent-last-sexp 0 t) (if (and (elt state 2) - ;; NOTE looking-at -> looking-at-p + ;; XXX: looking-at -> looking-at-p (not (looking-at-p "\\sw\\|\\s_"))) (progn - ;; NOTE (if (not ...) (progn ...)) -> (unless ... ...) + ;; XXX: (if (not ...) (progn ...)) -> (unless ... ...) (unless (> (save-excursion (forward-line 1) (point)) calculate-lisp-indent-last-sexp) (goto-char calculate-lisp-indent-last-sexp) @@ -23,7 +23,7 @@ property lists and names starting with 'default'." (parse-partial-sexp (point) calculate-lisp-indent-last-sexp 0 t)) (backward-prefix-chars) (current-column)) - ;; NOTE let -> let* & moved `method' def into let bindings + ;; XXX: let -> let* & moved `method' def into let bindings (let* ((function (buffer-substring (point) (progn (forward-sexp 1) (point)))) (method (or (get (intern-soft function) 'scheme-indent-function) @@ -31,15 +31,15 @@ property lists and names starting with 'default'." (cond ((or (eq method 'defun) (and (null method) (> (length function) 3) - ;; NOTE string-match -> string-match-p - ;; NOTE The original regexp is "\\`def" but it will mess - ;; up indentation with such names as 'default-...'. + ;; XXX: string-match -> string-match-p + ;; XXX: The original regexp is "\\`def" but it will mess + ;; up indentation with such names as 'default-...'. (string-match-p "\\`def" function))) (lisp-indent-defform state indent-point)) - ;; NOTE Added this clause to handle alignment of keyword symbols + ;; XXX: Added this clause to handle alignment of keyword symbols ((and (null method) (> (length function) 1) - ;; NOTE string-match -> string-match-p + ;; XXX: string-match -> string-match-p (string-match-p "\\`:" function)) (let ((lisp-body-indent 1)) (lisp-indent-defform state indent-point))) diff --git a/modules/lang/web/autoload/css.el b/modules/lang/web/autoload/css.el index 4d5279f1d..ff1667ab8 100644 --- a/modules/lang/web/autoload/css.el +++ b/modules/lang/web/autoload/css.el @@ -1,10 +1,10 @@ ;;; lang/web/autoload/css.el -*- lexical-binding: t; -*- ;; ;;;###autoload -;; TODO (defun +css/scss-build ()) +;; TODO: (defun +css/scss-build ()) ;; ;;;###autoload -;; TODO (defun +css/sass-build ()) +;; TODO: (defun +css/sass-build ()) (defun +css--toggle-inline-or-block (beg end) (skip-chars-forward " \t") diff --git a/modules/os/tty/config.el b/modules/os/tty/config.el index c1595a771..9dc29f58d 100644 --- a/modules/os/tty/config.el +++ b/modules/os/tty/config.el @@ -3,7 +3,7 @@ ;; Keep window title up-to-date. Should fail gracefully in non-xterm terminals. ;; Only works in Emacs 27+. (setq xterm-set-window-title t) -;; DEPRECATED Not needed on Emacs 28+. Remove when dropping 27 support. +;; DEPRECATED: Not needed on Emacs 28+. Remove when dropping 27 support. (defadvice! +tty--only-set-window-title-in-tty-a (&optional terminal) "`xterm-set-window-title' fails in GUI Emacs. Stop that. Get some help." :before-while #'xterm-set-window-title diff --git a/modules/os/tty/packages.el b/modules/os/tty/packages.el index d9d70f15a..308ec8ef8 100644 --- a/modules/os/tty/packages.el +++ b/modules/os/tty/packages.el @@ -8,8 +8,8 @@ ;; Despite its name, this works for macOS as well. (package! xclip :pin "9ab22517f3f2044e1c8c19be263da9803fbca26a")) -;; NOTE Despite the evil-* prefix, evil-terminal-cursor-changer does not depend -;; on evil (anymore). +;; Despite the evil-* prefix, evil-terminal-cursor-changer does not depend on +;; evil (anymore). (package! evil-terminal-cursor-changer :pin "2358f3e27d89128361cf80fcfa092fdfe5b52fd8") (package! kkp :pin "1a7b4f395aa4e1e04afc45fe2dbd6a045871803b") diff --git a/modules/term/eshell/autoload/backport.el b/modules/term/eshell/autoload/backport.el index 6024c1d2b..f37a835f8 100644 --- a/modules/term/eshell/autoload/backport.el +++ b/modules/term/eshell/autoload/backport.el @@ -1,9 +1,9 @@ ;;; term/eshell/autoload/mode.el -*- lexical-binding: t; -*- ;;;###if (< emacs-major-version 28) -;; DEPRECATED Remove this when we drop Emacs 27 support. +;; DEPRECATED: Remove this when we drop Emacs 27 support. -;; HACK Eshell resets its keymap every time `eshell-mode' is enabled. This is +;; HACK: Eshell resets its keymap every time `eshell-mode' is enabled. This is ;; fixed in Emacs 28+, but this file backports that fix for 27 users. This ;; way, keys can be safely bound to `eshell-mode-map' and `eshell-command-map' ;; like any normal keymap, rather than a hook. diff --git a/modules/term/eshell/autoload/company.el b/modules/term/eshell/autoload/company.el index 82f122fcf..e61cb673e 100644 --- a/modules/term/eshell/autoload/company.el +++ b/modules/term/eshell/autoload/company.el @@ -1,8 +1,6 @@ ;;; term/eshell/autoload/company.el -*- lexical-binding: t; -*- ;;;###if (modulep! :completion company) -;; REVIEW Refactor me - (defvar company-pcomplete-available 'unknown) (defun company-pcomplete--prefix () diff --git a/modules/term/eshell/autoload/prompts.el b/modules/term/eshell/autoload/prompts.el index 0c1dd6a40..7cf31c76b 100644 --- a/modules/term/eshell/autoload/prompts.el +++ b/modules/term/eshell/autoload/prompts.el @@ -12,7 +12,7 @@ (defun +eshell--current-git-branch () - ;; TODO Refactor me + ;; REVIEW: Refactor me (cl-destructuring-bind (status . output) (doom-call-process "git" "symbolic-ref" "-q" "--short" "HEAD") (if (equal status 0) diff --git a/modules/term/eshell/config.el b/modules/term/eshell/config.el index 086074b1f..ace2bac78 100644 --- a/modules/term/eshell/config.el +++ b/modules/term/eshell/config.el @@ -68,8 +68,8 @@ You should use `set-eshell-alias!' to change this.") eshell-scroll-to-bottom-on-output 'all eshell-kill-processes-on-exit t eshell-hist-ignoredups t - ;; don't record command in history if prefixed with whitespace - ;; TODO Use `eshell-input-filter-initial-space' when Emacs 25 support is dropped + ;; Don't record command in history if prefixed with whitespace + ;; TODO: Use `eshell-input-filter-initial-space' when Emacs 25 support is dropped eshell-input-filter (lambda (input) (not (string-match-p "\\`\\s-+" input))) ;; em-prompt eshell-prompt-regexp "^[^#$\n]* [#$λ] " diff --git a/modules/term/shell/autoload.el b/modules/term/shell/autoload.el index 7f758e520..cddc6f88b 100644 --- a/modules/term/shell/autoload.el +++ b/modules/term/shell/autoload.el @@ -101,5 +101,5 @@ If already in a shell buffer, clear it and cd into the current directory." buffer)) -;; TODO +shell/frame -- dedicate current frame to shell buffers -;; TODO +shell/frame-quite -- revert frame to before +term/frame +;; TODO: +shell/frame -- dedicate current frame to shell buffers +;; TODO: +shell/frame-quite -- revert frame to before +term/frame diff --git a/modules/term/term/autoload.el b/modules/term/term/autoload.el index 94d3b51e8..5b97c7486 100644 --- a/modules/term/term/autoload.el +++ b/modules/term/term/autoload.el @@ -43,5 +43,5 @@ If prefix ARG, recreate the term buffer." (defalias '+term/here #'multi-term) -;; TODO +term/frame -- dedicate current frame to term buffers -;; TODO +term/frame-quite -- revert frame to before +term/frame +;; TODO: +term/frame -- dedicate current frame to term buffers +;; TODO: +term/frame-quite -- revert frame to before +term/frame diff --git a/modules/term/vterm/autoload.el b/modules/term/vterm/autoload.el index 7fac10433..8d9ce04af 100644 --- a/modules/term/vterm/autoload.el +++ b/modules/term/vterm/autoload.el @@ -53,7 +53,7 @@ Returns the vterm buffer." arg (lambda() (require 'vterm) - ;; HACK forces vterm to redraw, fixing strange artefacting in the tty. + ;; HACK: Force vterm to redraw to fix artefacting in tty. (save-window-excursion (pop-to-buffer "*scratch*")) (let (display-buffer-alist) diff --git a/modules/term/vterm/config.el b/modules/term/vterm/config.el index 394730d1c..52acc5a5d 100644 --- a/modules/term/vterm/config.el +++ b/modules/term/vterm/config.el @@ -5,10 +5,10 @@ :commands vterm-mode :hook (vterm-mode . hide-mode-line-mode) ; modeline serves no purpose in vterm :preface - ;; HACK Because vterm clusmily forces vterm-module.so's compilation on us when - ;; the package is loaded, this is necessary to prevent it when - ;; byte-compiling this file (`use-package' blocks eagerly loads packages - ;; when compiled). + ;; HACK: Because vterm clusmily forces vterm-module.so's compilation on us + ;; when the package is loaded, this is necessary to prevent it when + ;; byte-compiling this file (`use-package' blocks eagerly loads packages + ;; when compiled). (when noninteractive (advice-add #'vterm-module-compile :override #'ignore) (provide 'vterm-module)) diff --git a/modules/tools/eval/config.el b/modules/tools/eval/config.el index 433eddb6a..ff7c77b80 100644 --- a/modules/tools/eval/config.el +++ b/modules/tools/eval/config.el @@ -91,8 +91,8 @@ buffer rather than an overlay on the line at point or the minibuffer.") (setq quickrun-option-outputter #'ignore) (funcall cb)))) - ;; HACK Without this, `+eval--inhibit-quickrun-popup-a' throws a - ;; window-live-p error because no window exists to be recentered! + ;; HACK: Without this, `+eval--inhibit-quickrun-popup-a' throws a + ;; window-live-p error because no window exists to be recentered! (advice-add #'quickrun--recenter :override #'ignore))) diff --git a/modules/tools/lookup/autoload/lookup.el b/modules/tools/lookup/autoload/lookup.el index 1ce100506..90ff42221 100644 --- a/modules/tools/lookup/autoload/lookup.el +++ b/modules/tools/lookup/autoload/lookup.el @@ -446,7 +446,7 @@ Otherwise, falls back on `find-file-at-point'." (defun +lookup/synonyms (identifier &optional _arg) "Look up and insert a synonym for the word at point (or selection)." (interactive - (list (doom-thing-at-point-or-region 'word) ; TODO actually use this + (list (doom-thing-at-point-or-region 'word) ; TODO: actually use this current-prefix-arg)) (message "Looking up synonyms for %S" identifier) (cond ((and +lookup-dictionary-prefer-offline diff --git a/modules/tools/lookup/config.el b/modules/tools/lookup/config.el index 3e8047c92..1779c35b5 100644 --- a/modules/tools/lookup/config.el +++ b/modules/tools/lookup/config.el @@ -168,8 +168,9 @@ Dictionary.app behind the scenes to get definitions.") (setq xref-show-definitions-function #'ivy-xref-show-defs xref-show-xrefs-function #'ivy-xref-show-xrefs) - ;; HACK Fix #4386: `ivy-xref-show-xrefs' calls `fetcher' twice, which has - ;; side effects that breaks in some cases (i.e. on `dired-do-find-regexp'). + ;; HACK: Fix #4386: `ivy-xref-show-xrefs' calls `fetcher' twice, which has + ;; side effects that breaks in some cases (i.e. on + ;; `dired-do-find-regexp'). (defadvice! +lookup--fix-ivy-xrefs (fn fetcher alist) :around #'ivy-xref-show-xrefs (when (functionp fetcher) diff --git a/modules/tools/lookup/packages.el b/modules/tools/lookup/packages.el index cc3e3313e..592c4b97c 100644 --- a/modules/tools/lookup/packages.el +++ b/modules/tools/lookup/packages.el @@ -1,9 +1,9 @@ ;; -*- no-byte-compile: t; -*- ;;; tools/lookup/packages.el -;; HACK `dumb-jump' uses the `helm-build-sync-source' macro, but this requires -;; helm be loaded before `dumb-jump' is byte-compiled during installation. -;; To ensure this, we declare helm before dumb-jump. +;; HACK: `dumb-jump' uses the `helm-build-sync-source' macro, but this requires +;; helm be loaded before `dumb-jump' is byte-compiled during installation. To +;; ensure this, we declare helm before dumb-jump. (when (modulep! :completion helm) (package! helm)) diff --git a/modules/tools/lsp/+lsp.el b/modules/tools/lsp/+lsp.el index b5e181e8a..de79c3ed6 100644 --- a/modules/tools/lsp/+lsp.el +++ b/modules/tools/lsp/+lsp.el @@ -21,10 +21,10 @@ Can be a list of backends; accepts any value `company-backends' accepts.") ;; will do it for you, after `+lsp-defer-shutdown' seconds. (setq lsp-keep-workspace-alive nil) - ;; NOTE I tweak LSP's defaults in order to make its more expensive or imposing - ;; features opt-in. Some servers implement these poorly and, in most - ;; cases, it's safer to rely on Emacs' native mechanisms (eldoc vs - ;; lsp-ui-doc, open in popup vs sideline, etc). + ;; NOTE: I tweak LSP's defaults in order to make its more expensive or + ;; imposing features opt-in. Some servers implement these poorly and, in + ;; most cases, it's safer to rely on Emacs' native mechanisms (eldoc vs + ;; lsp-ui-doc, open in popup vs sideline, etc). ;; Disable features that have great potential to be slow. (setq lsp-enable-folding nil diff --git a/modules/tools/lsp/autoload/eglot.el b/modules/tools/lsp/autoload/eglot.el index ae268ca84..ab92462b9 100644 --- a/modules/tools/lsp/autoload/eglot.el +++ b/modules/tools/lsp/autoload/eglot.el @@ -16,13 +16,13 @@ ALTERNATIVES specifies how to connect to a server in those modes." (eglot-alternatives alternatives) (car alternatives)))))) -;; HACK Eglot removed `eglot-help-at-point' in joaotavora/eglot@a044dec for a -;; more problematic approach of deferred to eldoc. Here, I've restored it. -;; Doom's lookup handlers try to open documentation in a separate window -;; (so they can be copied or kept open), but doing so with an eldoc buffer -;; is difficult because a) its contents are generated asynchronously, -;; making them tough to scrape, and b) their contents change frequently -;; (every time you move your cursor). +;; HACK: Eglot removed `eglot-help-at-point' in joaotavora/eglot@a044dec for a +;; more problematic approach of deferred to eldoc. Here, I've restored it. +;; Doom's lookup handlers try to open documentation in a separate window (so +;; they can be copied or kept open), but doing so with an eldoc buffer is +;; difficult because a) its contents are generated asynchronously, making them +;; tough to scrape, and b) their contents change frequently (every time you +;; move your cursor). (defvar +eglot--help-buffer nil) ;;;###autoload (defun +eglot-lookup-documentation (_identifier) diff --git a/modules/tools/lsp/config.el b/modules/tools/lsp/config.el index 9de57c3b8..fb9008b38 100644 --- a/modules/tools/lsp/config.el +++ b/modules/tools/lsp/config.el @@ -32,11 +32,10 @@ killing and opening many LSP/eglot-powered buffers.") (setq +lsp--default-read-process-output-max (default-value 'read-process-output-max) +lsp--default-gcmh-high-cons-threshold (default-value 'gcmh-high-cons-threshold)) (setq-default read-process-output-max (* 1024 1024)) - ;; REVIEW LSP causes a lot of allocations, with or without the native JSON - ;; library, so we up the GC threshold to stave off GC-induced - ;; slowdowns/freezes. Doom uses `gcmh' to enforce its GC strategy, - ;; so we modify its variables rather than `gc-cons-threshold' - ;; directly. + ;; REVIEW: LSP causes a lot of allocations, with or without the native + ;; JSON library, so we up the GC threshold to stave off GC-induced + ;; slowdowns/freezes. Doom uses `gcmh' to enforce its GC strategy, so we + ;; modify its variables rather than `gc-cons-threshold' directly. (setq-default gcmh-high-cons-threshold (* 2 +lsp--default-gcmh-high-cons-threshold)) (when (bound-and-true-p gcmh-mode) (gcmh-set-high-threshold)) diff --git a/modules/tools/magit/autoload.el b/modules/tools/magit/autoload.el index cd05fd061..7829e9c4f 100644 --- a/modules/tools/magit/autoload.el +++ b/modules/tools/magit/autoload.el @@ -1,9 +1,9 @@ ;;; tools/magit/autoload.el -*- lexical-binding: t; -*- -;; HACK Magit complains loudly (but harmlessly) when it can't determine its own -;; version in a sparse clone. Since I'd rather not compromise on shallow -;; clones, I've gimped `magit-version' so it doesn't complain (unless -;; called interactively). +;; HACK: Magit complains loudly (but harmlessly) when it can't determine its own +;; version in a sparse clone. Since I'd rather not compromise on shallow +;; clones, I've gimped `magit-version' so it doesn't complain (unless called +;; interactively). ;;;###autoload (defadvice! +magit--ignore-version-a (fn &rest args) :around #'magit-version diff --git a/modules/tools/magit/config.el b/modules/tools/magit/config.el index aa165bcd9..477d04a0b 100644 --- a/modules/tools/magit/config.el +++ b/modules/tools/magit/config.el @@ -203,8 +203,6 @@ FUNCTION :when (modulep! +forge) :after magit :init - ;; TODO This needs to either a) be cleaned up or better b) better map things - ;; to fit (after! evil-collection-magit (dolist (binding evil-collection-magit-mode-map-bindings) (pcase-let* ((`(,states _ ,evil-binding ,fn) binding)) @@ -247,8 +245,8 @@ FUNCTION "gm" #'forge-jump-to-pullreqs) ;; Fix these keybinds because they are blacklisted - ;; REVIEW There must be a better way to exclude particular evil-collection - ;; modules from the blacklist. + ;; REVIEW: There must be a better way to exclude particular evil-collection + ;; modules from the blacklist. (map! (:map magit-mode-map :nv "q" #'+magit/quit :nv "Q" #'+magit/quit-all diff --git a/modules/tools/pass/autoload/consult.el b/modules/tools/pass/autoload/consult.el index b58b8a6cf..8b0a6cea7 100644 --- a/modules/tools/pass/autoload/consult.el +++ b/modules/tools/pass/autoload/consult.el @@ -18,4 +18,4 @@ #'password-store-copy) pass)) -;; TODO Add embark actions to +pass/consult +;; TODO: Add embark actions to +pass/consult diff --git a/modules/tools/pass/config.el b/modules/tools/pass/config.el index aa593b077..e46ec99c9 100644 --- a/modules/tools/pass/config.el +++ b/modules/tools/pass/config.el @@ -14,7 +14,7 @@ (setq password-store-password-length 12) (after! evil-collection-pass - ;; FIXME This needs to be upstreamed to evil-collection. + ;; REVIEW: This needs to be upstreamed to evil-collection. (add-to-list 'evil-collection-pass-command-to-label '(pass-update-buffer . "gr"))) (after! pass diff --git a/modules/tools/pdf/config.el b/modules/tools/pdf/config.el index f6322bf87..6ab63769b 100644 --- a/modules/tools/pdf/config.el +++ b/modules/tools/pdf/config.el @@ -59,12 +59,12 @@ ;; The mode-line does serve any useful purpose is annotation windows (add-hook 'pdf-annot-list-mode-hook #'hide-mode-line-mode) - ;; HACK Fix #1107: flickering pdfs when evil-mode is enabled + ;; HACK: Fix #1107: flickering pdfs when evil-mode is enabled (setq-hook! 'pdf-view-mode-hook evil-normal-state-cursor (list nil)) - ;; HACK Refresh FG/BG for pdfs when `pdf-view-midnight-colors' is changed by a - ;; theme or with `setq!'. - ;; TODO PR this upstream? + ;; HACK: Refresh FG/BG for pdfs when `pdf-view-midnight-colors' is changed by + ;; a theme or with `setq!'. + ;; TODO: PR this upstream? (defun +pdf-reload-midnight-minor-mode-h () (when pdf-view-midnight-minor-mode (pdf-info-setoptions diff --git a/modules/tools/tmux/autoload/tmux.el b/modules/tools/tmux/autoload/tmux.el index 8c57ffb77..c81576aed 100644 --- a/modules/tools/tmux/autoload/tmux.el +++ b/modules/tools/tmux/autoload/tmux.el @@ -2,7 +2,7 @@ ;; This library offers: ;; + A way of communicating with a tmux instance -;; + TODO A way to manage tmuxifier from emacs +;; + TODO: A way to manage tmuxifier from emacs (defvar +tmux-last-command nil "The last command ran by `+tmux'. Used by `+tmux/rerun'") diff --git a/modules/ui/doom-dashboard/config.el b/modules/ui/doom-dashboard/config.el index 8a77d25e8..eb5ad2220 100644 --- a/modules/ui/doom-dashboard/config.el +++ b/modules/ui/doom-dashboard/config.el @@ -124,8 +124,8 @@ PLIST can have the following properties: ;; `persp-mode' integration: update `default-directory' when switching perspectives (add-hook 'persp-created-functions #'+doom-dashboard--persp-record-project-h) (add-hook 'persp-activated-functions #'+doom-dashboard--persp-detect-project-h) - ;; HACK Fix #2219 where, in GUI daemon frames, the dashboard loses center - ;; alignment after switching (or killing) workspaces. + ;; Fix #2219 where, in GUI daemon frames, the dashboard loses center + ;; alignment after switching (or killing) workspaces. (when (daemonp) (add-hook 'persp-activated-functions #'+doom-dashboard-reload-maybe-h)) (add-hook 'persp-before-switch-functions #'+doom-dashboard--persp-record-project-h))) diff --git a/modules/ui/hl-todo/config.el b/modules/ui/hl-todo/config.el index d4399307d..120a0cc1a 100644 --- a/modules/ui/hl-todo/config.el +++ b/modules/ui/hl-todo/config.el @@ -14,18 +14,24 @@ ;; For code that needs to be revisited later, either to upstream it, ;; improve it, or address non-critical issues. ("REVIEW" font-lock-keyword-face bold) - ;; For code smells where questionable practices are used - ;; intentionally, and/or is likely to break in a future update. + ;; For code smells where questionable practices are used intentionally + ;; and is likely to break in a future update. ("HACK" font-lock-constant-face bold) ;; For sections of code that just gotta go, and will be gone soon. ;; Specifically, this means the code is deprecated, not necessarily ;; the feature it enables. ("DEPRECATED" font-lock-doc-face bold) ;; Extra keywords commonly found in the wild, whose meaning may vary - ;; from project to project. - ("NOTE" success bold) + ;; from project to project. Doom doesn't use BUG. ("BUG" error bold) - ("XXX" font-lock-constant-face bold))) + ;; Doom uses XXX solely to highlight changes to the source in large + ;; :override advice functions. + ("XXX" font-lock-constant-face bold) + ;; Doom uses NOTE to indicate either A) this comment is about a code + ;; omission, e.g. "I *would've* put X here, but I didn't because Y", + ;; or B) it's a comment about a large section of code beyond the scope + ;; of adjacent lines. + ("NOTE" success bold))) (defadvice! +hl-todo-clamp-font-lock-fontify-region-a (fn &rest args) diff --git a/modules/ui/modeline/+light.el b/modules/ui/modeline/+light.el index 41d67b2f2..1eff62fa3 100644 --- a/modules/ui/modeline/+light.el +++ b/modules/ui/modeline/+light.el @@ -361,9 +361,9 @@ Requires `anzu', also `evil-anzu' if using `evil-mode' for compatibility with ;;; `+modeline-buffer-identification' (defvar-local +modeline--buffer-id-cache nil) -;; REVIEW Generating the buffer's file name can be relatively expensive. -;; Compounded with how often the modeline updates this can add up, so -;; we cache it ahead of time. +;; REVIEW: Generating the buffer's file name can be relatively expensive. +;; Compounded with how often the modeline updates this can add up, so we cache +;; it ahead of time. (add-hook! '(change-major-mode-after-body-hook ;; In case the user saves the file to a new location after-save-hook @@ -562,7 +562,7 @@ lines are selected, or the NxM dimensions of a block selection.") `("" +modeline-modes " ")) -;; TODO (def-modeline! helm ...) +;; TODO: (def-modeline! helm ...) ;; Other modes diff --git a/modules/ui/nav-flash/config.el b/modules/ui/nav-flash/config.el index 2a83a8b62..2c54fd090 100644 --- a/modules/ui/nav-flash/config.el +++ b/modules/ui/nav-flash/config.el @@ -13,12 +13,12 @@ ;; ;;; Packages -;; DEPRECATED To be replaced with pulsar.el when Emacs 28 support is dropped +;; DEPRECATED: To be replaced with pulsar.el when Emacs 28 support is dropped (use-package! nav-flash :defer t :init - ;; NOTE In :tools lookup `recenter' is hooked to a bunch of jumping - ;; commands, which will trigger nav-flash. + ;; In :tools lookup `recenter' is hooked to a bunch of jumping commands, which + ;; will trigger nav-flash. (add-hook! '(imenu-after-jump-hook better-jumper-post-jump-hook counsel-grep-post-action-hook diff --git a/modules/ui/popup/+hacks.el b/modules/ui/popup/+hacks.el index 2ce533438..09ef979fd 100644 --- a/modules/ui/popup/+hacks.el +++ b/modules/ui/popup/+hacks.el @@ -354,7 +354,7 @@ Ugh, such an ugly hack." (letf! (defun display-buffer-in-side-window (buffer alist) (+popup-display-buffer-stacked-side-window-fn buffer (append '((vslot . -9999) (select . t)) alist))) - ;; HACK Fix #2219 where the which-key popup would get cut off. + ;; HACK: Fix #2219 where the which-key popup would get cut off. (setcar act-popup-dim (1+ (car act-popup-dim))) (which-key--show-buffer-side-window act-popup-dim)))))) diff --git a/modules/ui/popup/autoload/popup.el b/modules/ui/popup/autoload/popup.el index 0fed3647b..dd657401d 100644 --- a/modules/ui/popup/autoload/popup.el +++ b/modules/ui/popup/autoload/popup.el @@ -24,9 +24,9 @@ the buffer is visible, then set another timer and try again later." (when (eq (process-type process) 'real) (kill-process process))) (let (kill-buffer-query-functions) - ;; HACK The debugger backtrace buffer, when killed, called - ;; `top-level'. This causes jumpiness when the popup - ;; manager tries to clean it up. + ;; HACK: The debugger backtrace buffer, when killed, called + ;; `top-level'. This causes jumpiness when the popup + ;; manager tries to clean it up. (cl-letf (((symbol-function #'top-level) #'ignore)) (kill-buffer buffer))))))) ((let ((ttl (if (= ttl 0) diff --git a/modules/ui/tabs/config.el b/modules/ui/tabs/config.el index 867f3e162..4909b7ee4 100644 --- a/modules/ui/tabs/config.el +++ b/modules/ui/tabs/config.el @@ -39,5 +39,5 @@ (when (centaur-tabs-mode-on-p) (centaur-tabs-local-mode))))) -;; TODO tab-bar-mode (emacs 27) -;; TODO tab-line-mode (emacs 27) +;; TODO: tab-bar-mode (emacs 27) +;; TODO: tab-line-mode (emacs 27) diff --git a/modules/ui/treemacs/config.el b/modules/ui/treemacs/config.el index f8608f018..5af68b6f2 100644 --- a/modules/ui/treemacs/config.el +++ b/modules/ui/treemacs/config.el @@ -64,8 +64,8 @@ This must be set before `treemacs' has loaded.") [return] #'treemacs-RET-action [tab] #'treemacs-TAB-action "TAB" #'treemacs-TAB-action - ;; REVIEW Fix #1875 to be consistent with C-w {v,s}, but this should really - ;; be considered upstream. + ;; REVIEW: Fix #1875 to be consistent with C-w {v,s}, but this should really + ;; be considered upstream. "o v" #'treemacs-visit-node-horizontal-split "o s" #'treemacs-visit-node-vertical-split)) diff --git a/modules/ui/workspaces/autoload/workspaces.el b/modules/ui/workspaces/autoload/workspaces.el index 9977b09b5..1306101a4 100644 --- a/modules/ui/workspaces/autoload/workspaces.el +++ b/modules/ui/workspaces/autoload/workspaces.el @@ -261,7 +261,6 @@ workspace to delete." nil nil nil nil current-name) current-name)))) (condition-case-unless-debug ex - ;; REVIEW refactor me (let ((workspaces (+workspace-list-names))) (if (not (member name workspaces)) (+workspace-message (format "'%s' workspace doesn't exist" name) 'warn) diff --git a/modules/ui/workspaces/config.el b/modules/ui/workspaces/config.el index 225033397..c420bc933 100644 --- a/modules/ui/workspaces/config.el +++ b/modules/ui/workspaces/config.el @@ -5,7 +5,7 @@ ;; it because it was unstable and slow; `persp-mode' is neither (and still ;; maintained). ;; -;; NOTE persp-mode requires `workgroups' for file persistence in Emacs 24.4. +;; NOTE: persp-mode requires `workgroups' for file persistence in Emacs 24.4. (defvar +workspaces-main "main" "The name of the primary and initial workspace, which cannot be deleted.") @@ -25,7 +25,7 @@ t Always create a new workspace for the project associated with it. nil Never create a new workspace on project switch.") -;; FIXME actually use this for wconf bookmark system +;; FIXME: Actually use this for wconf bookmark system (defvar +workspaces-data-file "_workspaces" "The basename of the file to store single workspace perspectives. Will be stored in `persp-save-dir'.") @@ -77,8 +77,8 @@ stored in `persp-save-dir'.") ;; Start from 2 b/c persp-mode counts the nil workspace (> (hash-table-count *persp-hash*) 2)) (persp-add-new +workspaces-main)) - ;; HACK Fix #319: the warnings buffer gets swallowed when creating - ;; `+workspaces-main', so display it ourselves, if it exists. + ;; HACK: Fix #319: the warnings buffer gets swallowed when creating + ;; `+workspaces-main', so display it ourselves, if it exists. (when-let (warnings (get-buffer "*Warnings*")) (unless (get-buffer-window warnings) (save-excursion @@ -86,10 +86,10 @@ stored in `persp-save-dir'.") warnings '((window-height . shrink-window-if-larger-than-buffer))))))))) (defun +workspaces-init-persp-mode-h () (cond (persp-mode - ;; `uniquify' breaks persp-mode. It renames old buffers, which causes - ;; errors when switching between perspective (their buffers are - ;; serialized by name and persp-mode expects them to have the same - ;; name when restored). + ;; `uniquify' breaks persp-mode. It renames old buffers, which + ;; causes errors when switching between perspective (their buffers + ;; are serialized by name and persp-mode expects them to have the + ;; same name when restored). (when uniquify-buffer-name-style (setq +workspace--old-uniquify-style uniquify-buffer-name-style)) (setq uniquify-buffer-name-style nil) @@ -153,13 +153,13 @@ stored in `persp-save-dir'.") (cadr prev-buffers) head))) - ;; HACK Fixes #4196, #1525: selecting deleted buffer error when quitting Emacs - ;; or on some buffer listing ops. + ;; HACK: Fixes #4196, #1525: selecting deleted buffer error when quitting + ;; Emacs or on some buffer listing ops. (defadvice! +workspaces-remove-dead-buffers-a (persp) :before #'persp-buffers-to-savelist (when (perspective-p persp) - ;; HACK Can't use `persp-buffers' because of a race condition with its gv - ;; getter/setter not being defined in time. + ;; HACK: Can't use `persp-buffers' because of a race condition with its gv + ;; getter/setter not being defined in time. (setf (aref persp 2) (cl-delete-if-not #'persp-get-buffer-or-null (persp-buffers persp))))) @@ -176,8 +176,8 @@ stored in `persp-save-dir'.") (add-hook 'delete-frame-functions #'+workspaces-delete-associated-workspace-h) (add-hook 'server-done-hook #'+workspaces-delete-associated-workspace-h) - ;; per-project workspaces, but reuse current workspace if empty - ;; HACK?? needs review + ;; Per-project workspaces, but reuse current workspace if empty + ;; REVIEW: Remove when ivy module is removed (setq projectile-switch-project-action #'+workspaces-switch-to-project-h counsel-projectile-switch-project-action '(1 ("o" +workspaces-switch-to-project-h "open project in new workspace") diff --git a/static/init.example.el b/static/init.example.el index 8d3167694..d4e4e0c71 100644 --- a/static/init.example.el +++ b/static/init.example.el @@ -3,16 +3,16 @@ ;; This file controls what Doom modules are enabled and what order they load ;; in. Remember to run 'doom sync' after modifying it! -;; NOTE Press 'SPC h d h' (or 'C-h d h' for non-vim users) to access Doom's -;; documentation. There you'll find a link to Doom's Module Index where all -;; of our modules are listed, including what flags they support. +;; NOTE: Press 'SPC h d h' (or 'C-h d h' for non-vim users) to access Doom's +;; documentation. There you'll find a link to Doom's Module Index where all of +;; our modules are listed, including what flags they support. -;; NOTE Move your cursor over a module's name (or its flags) and press 'K' (or -;; 'C-c c k' for non-vim users) to view its documentation. This works on -;; flags as well (those symbols that start with a plus). +;; NOTE: Move your cursor over a module's name (or its flags) and press 'K' (or +;; 'C-c c k' for non-vim users) to view its documentation. This works on flags +;; as well (those symbols that start with a plus). ;; -;; Alternatively, press 'gd' (or 'C-c c d') on a module to browse its -;; directory (for easy access to its source code). +;; Alternatively, press 'gd' (or 'C-c c d') on a module to browse its +;; directory (for easy access to its source code). (doom! :input ;;bidi ; (tfel ot) thgir etirw uoy gnipleh @@ -92,7 +92,7 @@ ;;ansible ;;biblio ; Writes a PhD for you (citation needed) ;;collab ; buffers with friends - ;;debugger ; FIXME stepping through code, to help you add bugs + ;;debugger ; stepping through code, to help you add bugs ;;direnv ;;docker ;;editorconfig ; let someone else argue about tabs vs spaces