From 6d314c2795a804249a449c84b86e094d99d73367 Mon Sep 17 00:00:00 2001 From: Henrik Lissner Date: Wed, 1 May 2019 19:12:52 -0400 Subject: [PATCH] Revise and update docstrings and comments --- core/autoload/help.el | 13 +-- core/autoload/message.el | 2 + core/cli/autoloads.el | 41 ++++++--- core/cli/quickstart.el | 29 +++++-- core/core-cli.el | 5 +- core/core-lib.el | 111 ++++++++---------------- core/core-modules.el | 89 ++++++++++++++++--- core/core.el | 81 ++++++++++------- core/templates/QUICKSTART_INTRO | 21 ++--- modules/config/default/config.el | 2 +- modules/lang/emacs-lisp/autoload.el | 6 +- modules/lang/emacs-lisp/config.el | 11 ++- modules/lang/web/+css.el | 7 +- modules/lang/web/autoload/css.el | 5 +- modules/lang/web/autoload/evil.el | 4 +- modules/lang/web/autoload/html.el | 10 ++- modules/tools/lookup/autoload/lookup.el | 28 ++++-- 17 files changed, 276 insertions(+), 189 deletions(-) diff --git a/core/autoload/help.el b/core/autoload/help.el index 1aadc057a..1910ccb32 100644 --- a/core/autoload/help.el +++ b/core/autoload/help.el @@ -67,7 +67,10 @@ (stylus-mode :lang web) (terra-mode :lang terra) (vala-mode :lang vala)) - "TODO") + "An alist mapping major modes to Doom modules. + +This is used by `doom/help-modules' to auto-select the module corresponding to +the current major-modea.") ;; @@ -201,12 +204,12 @@ The latest newsletter will be selected by default." ;;;###autoload (defun doom/help-autodefs (autodef) - "Open the documentation of an autodef. + "Open documentation for an autodef. An autodef is a Doom concept. It is a function or macro that is always defined, whether or not its containing module is disabled (in which case it will safely -no-op). This syntactic sugar lets you use them without needing to check if they -are available." +no-op without evaluating its arguments). This syntactic sugar lets you use them +without needing to check if they are available." (interactive (let* ((settings (cl-loop with case-fold-search = nil @@ -427,7 +430,7 @@ If prefix arg is present, refresh the cache." ;;;###autoload (defun doom/help-package-config (package) - "Jump to a configuration block for PACKAGE." + "Jump to any `def-package!', `after!' or ;;;###package block for PACKAGE." (interactive (list (doom--completing-package "Select package to search for: " current-prefix-arg))) (let* ((default-directory doom-emacs-dir) diff --git a/core/autoload/message.el b/core/autoload/message.el index 358272aac..b2b0d6aa0 100644 --- a/core/autoload/message.el +++ b/core/autoload/message.el @@ -39,6 +39,7 @@ Accepts 'ansi and 'text-properties. nil means don't render colors.") ;;;###autoload (defun doom-message-indent (width text &rest args) + "Indent TEXT by WIDTH spaces. If ARGS, format TEXT with them." (with-temp-buffer (insert (apply #'format text args)) (let ((fill-column 80)) @@ -53,6 +54,7 @@ Accepts 'ansi and 'text-properties. nil means don't render colors.") ;;;###autoload (defun doom-message-autofill (&rest msgs) + "Ensure MSG is split into lines no longer than `fill-column'." (with-temp-buffer (let ((fill-column 70)) (dolist (line msgs) diff --git a/core/cli/autoloads.el b/core/cli/autoloads.el index 84678d50e..ff68e1eb8 100644 --- a/core/cli/autoloads.el +++ b/core/cli/autoloads.el @@ -1,10 +1,15 @@ ;;; core/cli/autoloads.el -*- lexical-binding: t; -*- (dispatcher! (autoloads a) (doom-reload-autoloads nil 'force) - "Regenerates Doom's autoloads file. + "Regenerates Doom's autoloads files. -This file tells Emacs where to find your module's autoloaded functions and -plugins.") +It scans and reads autoload cookies (;;;###autoload) in core/autoload/*.el, +modules/*/*/autoload.el and modules/*/*/autoload/*.el, and generates +`doom-autoload-file', then compiles `doom-package-autoload-file' from the +concatenated autoloads files of all installed packages. + +It also caches `load-path', `Info-directory-list', `doom-disabled-packages', +`package-activated-list' and `auto-mode-alist'.") ;; external variables (defvar autoload-timestamps) @@ -13,7 +18,7 @@ plugins.") ;; -;; Helpers +;;; Helpers (defvar doom-autoload-excluded-packages '(marshal gh) "Packages that have silly or destructive autoload files that try to load @@ -86,7 +91,7 @@ even if it doesn't need reloading!" ;; -;; Doom autoloads +;;; Doom autoloads (defun doom--file-cookie-p (file) "Returns the return value of the ;;;###if predicate form in FILE." @@ -227,15 +232,13 @@ even if it doesn't need reloading!" (replace-match "" t t))) (defun doom-reload-doom-autoloads (&optional force-p) - "Refreshes the autoloads.el file, specified by `doom-autoload-file', if -necessary (or if FORCE-P is non-nil). + "Refreshes `doom-autoload-file', if necessary (or if FORCE-P is non-nil). -It scans and reads core/autoload/*.el, modules/*/*/autoload.el and -modules/*/*/autoload/*.el, and generates `doom-autoload-file'. This file tells -Emacs where to find lazy-loaded functions. +It scans and reads autoload cookies (;;;###autoload) in core/autoload/*.el, +modules/*/*/autoload.el and modules/*/*/autoload/*.el, and generates +`doom-autoload-file'. -This should be run whenever your `doom!' block, or a module autoload file, is -modified." +Run this whenever your `doom!' block, or a module autoload file, is modified." (let* ((default-directory doom-emacs-dir) (doom-modules (doom-modules)) (targets @@ -284,7 +287,7 @@ modified." (save-excursion (doom--generate-autodefs (reverse targets) enabled-targets) (print! (green "✓ Generated autodefs"))) - ;; Remove byte-compile inhibiting file variables so we can byte-compile + ;; Remove byte-compile-inhibiting file variables so we can byte-compile ;; the file, and autoload comments. (doom--cleanup-autoloads) (print! (green "✓ Clean up autoloads"))) @@ -295,9 +298,13 @@ modified." ;; -;; Package autoloads +;;; Package autoloads (defun doom--generate-package-autoloads () + "Concatenates package autoload files, let-binds `load-file-name' around +them,and remove unnecessary `provide' statements or blank links. + +Skips over packages in `doom-autoload-excluded-packages'." (dolist (spec (doom-get-package-alist)) (if-let* ((pkg (car spec)) (desc (cdr spec))) @@ -314,6 +321,8 @@ modified." (message "Couldn't find package desc for %s" (car spec))))) (defun doom--generate-var-cache () + "Print a `setq' form for expensive-to-initialize variables, so we can cache +them in Doom's autoloads file." (doom-initialize-packages) (prin1 `(setq load-path ',load-path auto-mode-alist ',auto-mode-alist @@ -323,6 +332,10 @@ modified." (current-buffer))) (defun doom--cleanup-package-autoloads () + "Remove (some) forms that modify `load-path' or `auto-mode-alist'. + +These variables are cached all at once and at later, so these removed statements +served no purpose but to waste cycles." (while (re-search-forward "^\\s-*\\((\\(?:add-to-list\\|\\(?:when\\|if\\) (boundp\\)\\s-+'\\(?:load-path\\|auto-mode-alist\\)\\)" nil t) (goto-char (match-beginning 1)) (kill-sexp))) diff --git a/core/cli/quickstart.el b/core/cli/quickstart.el index d67795fd4..8f83cc5ba 100644 --- a/core/cli/quickstart.el +++ b/core/cli/quickstart.el @@ -1,31 +1,42 @@ ;;; core/cli/quickstart.el -*- lexical-binding: t; -*- (dispatcher! (quickstart qs) (apply #'doom-quickstart args) - "Quickly deploy a private module and Doom. + "Guides you through setting up Doom for first time use. -This deploys a barebones config to ~/.doom.d (if it doesn't already exist). The -destination can be changed with the -p option, e.g. +This command does the following: + +1. Creates DOOMDIR at ~/.doom.d, +2. Copies ~/.emacs.d/init.example.el to DOOMDIR/init.el (if it doesn't exist), +3. Creates dummy files for DOOMDIR/{config,packages}.el, +4. Prompts you to generate an envvar file (via 'doom env refresh'), +5. Installs any dependencies of enabled modules (specified by DOOMDIR/init.el), +6. And prompts to install all-the-icons' fonts + +This command is idempotent and safe to reuse. + +The location of DOOMDIR can be changed with the -p option, or by setting the +DOOMDIR environment variable. e.g. doom -p ~/.config/doom quickstart + DOOMDIR=~/.config/doom doom quickstart Quickstart understands the following switches: - --no-config Don't deploy dummy config to ~/.doom.d + --no-config Don't create DOOMDIR or dummy files therein --no-install Don't auto-install packages --no-env Don't generate an envvars file (see `doom help env`) - --no-fonts Don't install (or prompt to install) all-the-icons fonts - -This command is idempotent and is safe to reuse.") + --no-fonts Don't install (or prompt to install) all-the-icons fonts") ;; ;; Library (defun doom-quickstart (&rest args) - "Quickly deploy a private module and Doom. + "Quickly deploy a private module and setup Doom. This deploys a barebones config to `doom-private-dir', installs all missing -packages and regenerates the autoloads file." +packages, prompts to install all-the-icons fonts, generates an env file and +regenerates the autoloads file." ;; Create `doom-private-dir' (let ((short-private-dir (abbreviate-file-name doom-private-dir))) (if (member "--no-config" args) diff --git a/core/core-cli.el b/core/core-cli.el index 86da98fe2..7ca20ba45 100644 --- a/core/core-cli.el +++ b/core/core-cli.el @@ -90,7 +90,10 @@ BODY will be run when this dispatcher is called." ;; -;; Dummy dispatch commands (no-op because they're handled especially) +;; Dummy dispatch commands + +;; These are handled by bin/doom, except we still want 'help CMD' to print out +;; documentation for them, so... (dispatcher! run :noop "Run Doom Emacs from bin/doom's parent directory. diff --git a/core/core-lib.el b/core/core-lib.el index e02c31abf..6c50a5b41 100644 --- a/core/core-lib.el +++ b/core/core-lib.el @@ -48,6 +48,9 @@ This is used by `associate!', `file-exists-p!' and `project-file-exists-p!'." (spec))) (defun doom--resolve-hook-forms (hooks) + "Converts a list of modes into a list of hook symbols. + +If a mode is quoted, it is left as is." (declare (pure t) (side-effect-free t)) (cl-loop with quoted-p = (eq (car-safe hooks) 'quote) for hook in (doom-enlist (doom-unquote hooks)) @@ -129,7 +132,7 @@ Accepts the same arguments as `message'." ;; Macros (defmacro λ! (&rest body) - "A shortcut for inline interactive lambdas." + "Expands to (lambda () (interactive) ,@body)." (declare (doc-string 1)) `(lambda () (interactive) ,@body)) @@ -180,70 +183,21 @@ reverse this and trigger `after!' blocks at a more reasonable time." (setq features (delq ',feature features)) (advice-add #',mode :before #',advice-fn) (defun ,advice-fn (&rest _) - ;; Some plugins (like yasnippet) will invoke a mode early, e.g. to - ;; parse some code. This would prematurely trigger this function. This - ;; checks for that: + ;; Some plugins (like yasnippet) will invoke a mode early to parse + ;; code, which would prematurely trigger this. In those cases, well + ;; behaved plugins will use `delay-mode-hooks', which we can check for: (when (and ,(intern (format "%s-hook" mode)) (not delay-mode-hooks)) - ;; Otherwise, announce to the world this package has been loaded, so - ;; `after!' handlers can respond and configure elisp-mode as - ;; expected. + ;; ...Otherwise, announce to the world this package has been loaded, + ;; so `after!' handlers can react. (provide ',feature) (advice-remove #',mode #',advice-fn)))))) -(defmacro after! (targets &rest body) - "A smart wrapper around `with-eval-after-load' that: - -1. Suppresses warnings at compile-time -2. No-ops for TARGETS that are disabled by the user (via `package!') -3. Supports compound TARGETS statements (see below) - -BODY is evaluated once TARGETS are loaded. TARGETS can either be: - -- An unquoted package symbol (the name of a package) - - (after! helm ...) - -- An unquoted list of package symbols - - (after! (magit git-gutter) ...) - -- An unquoted, nested list of compound package lists, using :or/:any and/or :and/:all - - (after! (:or package-a package-b ...) ...) - (after! (:and package-a package-b ...) ...) - (after! (:and package-a (:or package-b package-c) ...) ...) - - Note that: - - :or and :any are equivalent - - :and and :all are equivalent - - If these are omitted, :and is assumed." - (declare (indent defun) (debug t)) - (unless (and (symbolp targets) - (memq targets (bound-and-true-p doom-disabled-packages))) - (list (if (or (not (bound-and-true-p byte-compile-current-file)) - (dolist (next (doom-enlist targets)) - (unless (keywordp next) - (if (symbolp next) - (require next nil :no-error) - (load next :no-message :no-error))))) - #'progn - #'with-no-warnings) - (if (symbolp targets) - `(with-eval-after-load ',targets ,@body) - (pcase (car-safe targets) - ((or :or :any) - (macroexp-progn - (cl-loop for next in (cdr targets) - collect `(after! ,next ,@body)))) - ((or :and :all) - (dolist (next (cdr targets)) - (setq body `((after! ,next ,@body)))) - (car body)) - (_ `(after! (:and ,@targets) ,@body))))))) - (defmacro quiet! (&rest forms) - "Run FORMS without making any output." + "Run FORMS without generating any output. + +This silences calls to `message', `load-file', `write-region' and anything that +writes to `standard-output'." `(cond (noninteractive (let ((old-fn (symbol-function 'write-region))) (cl-letf ((standard-output (lambda (&rest _))) @@ -263,7 +217,7 @@ BODY is evaluated once TARGETS are loaded. TARGETS can either be: (defmacro add-transient-hook! (hook-or-function &rest forms) "Attaches a self-removing function to HOOK-OR-FUNCTION. -FORMS are evaluated once when that function/hook is first invoked, then never +FORMS are evaluated once, when that function/hook is first invoked, then never again. HOOK-OR-FUNCTION can be a quoted hook or a sharp-quoted function (which will be @@ -287,14 +241,19 @@ advised)." (add-hook ,hook-or-function #',fn ,append)))))) (defmacro add-hook! (&rest args) - "A convenience macro for `add-hook'. Takes, in order: + "A convenience macro for adding N functions to M hooks. + +If N and M = 1, there's no benefit to using this macro over `add-hook'. + +This macro accepts, in order: 1. Optional properties :local and/or :append, which will make the hook buffer-local or append to the list of hooks (respectively), - 2. The hooks: either an unquoted major mode, an unquoted list of major-modes, - a quoted hook variable or a quoted list of hook variables. If unquoted, the - hooks will be resolved by appending -hook to each symbol. - 3. A function, list of functions, or body forms to be wrapped in a lambda. + 2. The hook(s) to be added to: either an unquoted mode, an unquoted list of + modes, a quoted hook variable or a quoted list of hook variables. If + unquoted, '-hook' will be appended to each symbol. + 3. The function(s) to be added: this can be one function, a list thereof, or + body forms (implicitly wrapped in a closure). Examples: (add-hook! 'some-mode-hook 'enable-something) (same as `add-hook') @@ -306,9 +265,6 @@ Examples: (add-hook! (one-mode second-mode) (setq v 5) (setq a 2)) (add-hook! :append :local (one-mode second-mode) (setq v 5) (setq a 2)) -Body forms can access the hook's arguments through the let-bound variable -`args'. - \(fn [:append :local] HOOKS FUNCTIONS)" (declare (indent defun) (debug t)) (let ((hook-fn 'add-hook) @@ -339,19 +295,24 @@ Body forms can access the hook's arguments through the let-bound variable `(progn ,@(if append-p (nreverse forms) forms))))) (defmacro remove-hook! (&rest args) - "Convenience macro for `remove-hook'. Takes the same arguments as -`add-hook!'. + "A convenience macro for removing N functions from M hooks. + +Takes the same arguments as `add-hook!'. + +If N and M = 1, there's no benefit to using this macro over `remove-hook'. \(fn [:append :local] HOOKS FUNCTIONS)" (declare (indent defun) (debug t)) `(add-hook! :remove ,@args)) (defmacro setq-hook! (hooks &rest rest) - "Convenience macro for setting buffer-local variables in a hook. + "Sets buffer-local variables on HOOKS. (setq-hook! 'markdown-mode-hook line-spacing 2 - fill-column 80)" + fill-column 80) + +\(fn HOOKS &rest SYM VAL...)" (declare (indent 1)) (unless (= 0 (% (length rest) 2)) (signal 'wrong-number-of-arguments (list #'evenp (length rest)))) @@ -363,7 +324,7 @@ Body forms can access the hook's arguments through the let-bound variable (push `(setq-local ,var ,val) forms))) (nreverse forms)))) -(defun advice-add! (symbols where functions) +(defun advice-add! (symbols where functions) "Variadic version of `advice-add'. SYMBOLS and FUNCTIONS can be lists of functions." @@ -400,8 +361,8 @@ The available conditions are: :match REGEXP A regexp to be tested against the current file path. :files SPEC - Accepts what `project-file-exists-p!' accepts. Checks if certain files exist - relative to the project root. + Accepts what `project-file-exists-p!' accepts. Checks if certain files or + directories exist relative to the project root. :when FORM Whenever FORM returns non-nil." (declare (indent 1)) diff --git a/core/core-modules.el b/core/core-modules.el index dfa23c713..07fce1326 100644 --- a/core/core-modules.el +++ b/core/core-modules.el @@ -233,10 +233,17 @@ non-nil, return paths of possible modules, activated or otherwise." ;; ;; Check out `def-package!'s documentation for more about these two. (defvar doom--deferred-packages-alist '(t)) -(after! use-package-core - ;; :ensure and :pin don't work well with Doom, so we forcibly remove them. - (dolist (keyword '(:ensure :pin)) - (delq! keyword use-package-keywords)) + +(with-eval-after-load 'use-package-core + ;; Macros are already fontified, no need for this + (font-lock-remove-keywords 'emacs-lisp-mode use-package-font-lock-keywords) + + ;; Disable :ensure and :pin, because they don't work with Doom because we do + ;; our own package management. + (with-eval-after-load 'use-package-ensure + (dolist (keyword '(:ensure :pin)) + (delq! keyword use-package-keywords) + (delq! keyword use-package-defaults 'assq))) ;; Insert new deferring keywords (dolist (keyword '(:defer-incrementally :after-call)) @@ -355,11 +362,13 @@ to least)." (defvar doom-disabled-packages) (defmacro def-package! (name &rest plist) - "This is a thin wrapper around `use-package'. + "Declares and configures a package. -It is ignored if the NAME package is disabled. +This is a thin wrapper around `use-package', and is ignored if the NAME package +is disabled by the user (with `package!'). -Supports two special properties over `use-package': +See `use-package' to see what properties can be provided. Doom adds support for +two extra properties: :after-call SYMBOL|LIST Takes a symbol or list of symbols representing functions or hook variables. @@ -380,15 +389,15 @@ Supports two special properties over `use-package': NAME is implicitly added if this property is present and non-nil. No need to specify it. A value of `t' implies NAME, e.g. - (def-package! x - ;; This is equivalent to :defer-incrementally (x) + (def-package! abc + ;; This is equivalent to :defer-incrementally (abc) :defer-incrementally t ...)" (unless (or (memq name doom-disabled-packages) - ;; At compile-time, use-package will forcibly load its package to - ;; prevent compile-time errors. However, Doom users can - ;; intentionally disable packages, resulting if file-missing - ;; package errors, so we preform this check at compile time: + ;; At compile-time, use-package will forcibly load packages to + ;; prevent compile-time errors. However, if a Doom user has + ;; disabled packages you get file-missing package errors, so it's + ;; necessary to check for packages at compile time: (and (bound-and-true-p byte-compile-current-file) (not (locate-library (symbol-name name))))) `(use-package ,name ,@plist))) @@ -478,5 +487,59 @@ CATEGORY and MODULE can be omitted When this macro is used from inside a module (memq category (doom-module-get (car module-pair) (cdr module-pair) :flags))))) t)) +(defmacro after! (targets &rest body) + "Evaluate BODY after TARGETS have loaded. + +This is a wrapper around `with-eval-after-load' that: + +1. Suppresses warnings for disabled packages at compile-time +2. No-ops for TARGETS that are disabled by the user (via `package!') +3. Supports compound TARGETS statements (see below) + +TARGETS can either be: + +- An unquoted package symbol (the name of a package) + + (after! helm BODY...) + +- An unquoted list of package symbols (i.e. BODY is evaluated once both magit + and git-gutter have loaded) + + (after! (magit git-gutter) BODY...) + +- An unquoted, nested list of compound package lists, using :or/:any and/or :and/:all + + (after! (:or package-a package-b ...) BODY...) + (after! (:and package-a package-b ...) BODY...) + (after! (:and package-a (:or package-b package-c) ...) BODY...) + +Note that: +- :or and :any are equivalent +- :and and :all are equivalent +- If these are omitted, :and is implied." + (declare (indent defun) (debug t)) + (unless (and (symbolp targets) + (memq targets (bound-and-true-p doom-disabled-packages))) + (list (if (or (not (bound-and-true-p byte-compile-current-file)) + (dolist (next (doom-enlist targets)) + (unless (keywordp next) + (if (symbolp next) + (require next nil :no-error) + (load next :no-message :no-error))))) + #'progn + #'with-no-warnings) + (if (symbolp targets) + `(with-eval-after-load ',targets ,@body) + (pcase (car-safe targets) + ((or :or :any) + (macroexp-progn + (cl-loop for next in (cdr targets) + collect `(after! ,next ,@body)))) + ((or :and :all) + (dolist (next (cdr targets)) + (setq body `((after! ,next ,@body)))) + (car body)) + (_ `(after! (:and ,@targets) ,@body))))))) + (provide 'core-modules) ;;; core-modules.el ends here diff --git a/core/core.el b/core/core.el index 37a61633a..9dd31a31c 100644 --- a/core/core.el +++ b/core/core.el @@ -6,15 +6,17 @@ emacs-version))) (defvar doom-debug-mode (or (getenv "DEBUG") init-file-debug) - "If non-nil, all doom functions will be verbose. Set DEBUG=1 in the command -line or use --debug-init to enable this.") + "If non-nil, Doom will log more. + +Use `doom/toggle-debug-mode' to toggle it. The --debug-init flag and setting the +DEBUG envvar will enable this at startup.") ;; ;;; Constants (defconst doom-version "2.0.9" - "Current version of DOOM emacs.") + "Current version of Doom Emacs.") (defconst EMACS26+ (> emacs-major-version 25)) (defconst EMACS27+ (> emacs-major-version 26)) @@ -28,35 +30,39 @@ line or use --debug-init to enable this.") ;; (defvar doom-emacs-dir (eval-when-compile (file-truename user-emacs-directory)) - "The path to this emacs.d directory. Must end in a slash.") + "The path to the currently loaded .emacs.d directory. Must end with a slash.") (defvar doom-core-dir (concat doom-emacs-dir "core/") - "The root directory of core Doom files.") + "The root directory of Doom's core files. Must end with a slash.") (defvar doom-modules-dir (concat doom-emacs-dir "modules/") - "The root directory for Doom's modules.") + "The root directory for Doom's modules. Must end with a slash.") (defvar doom-local-dir (concat doom-emacs-dir ".local/") - "Root directory for local Emacs files. Use this as permanent storage for files -that are safe to share across systems (if this config is symlinked across -several computers).") + "Root directory for local storage. + +Use this as a storage location for this system's installation of Doom Emacs. +These files should not be shared across systems. By default, it is used by +`doom-etc-dir' and `doom-cache-dir'. Must end with a slash.") (defvar doom-etc-dir (concat doom-local-dir "etc/") - "Directory for non-volatile storage. + "Directory for non-volatile local storage. -Use this for files that don't change much, like servers binaries, external -dependencies or long-term shared data.") +Use this for files that don't change much, like server binaries, external +dependencies or long-term shared data. Must end with a slash.") (defvar doom-cache-dir (concat doom-local-dir "cache/") - "Directory for volatile storage. + "Directory for volatile local storage. -Use this for files that change often, like cache files.") +Use this for files that change often, like cache files. Must end with a slash.") (defvar doom-packages-dir (concat doom-local-dir "packages/") - "Where package.el and quelpa plugins (and their caches) are stored.") + "Where package.el and quelpa plugins (and their caches) are stored. + +Must end with a slash.") (defvar doom-docs-dir (concat doom-emacs-dir "docs/") - "Where the Doom manual is stored.") + "Where Doom's documentation files are stored. Must end with a slash.") (defvar doom-private-dir (or (getenv "DOOMDIR") @@ -66,37 +72,44 @@ Use this for files that change often, like cache files.") "~/.config")))) (if (file-directory-p xdg-path) xdg-path)) "~/.doom.d/") - "Where your private customizations are placed. Must end in a slash. Respects -XDG directory conventions if ~/.config/doom exists.") + "Where your private configuration is placed. + +Defaults to ~/.config/doom, ~/.doom.d or the value of the DOOMDIR envvar; +whichever is found first. Must end in a slash.") (defvar doom-autoload-file (concat doom-local-dir "autoloads.el") - "Where `doom-reload-doom-autoloads' will generate its core autoloads file.") + "Where `doom-reload-doom-autoloads' stores its core autoloads. + +This file is responsible for informing Emacs where to find all of Doom's +autoloaded core functions (in core/autoload/*.el).") (defvar doom-package-autoload-file (concat doom-local-dir "autoloads.pkg.el") - "Where `doom-reload-package-autoloads' will generate its package.el autoloads -file.") + "Where `doom-reload-package-autoloads' stores its package.el autoloads. + +This file is compiled from the autoloads files of all installed packages +combined.") (defvar doom-env-file (concat doom-local-dir "env") - "The location of your env file, generated by `doom env refresh`. + "The location of your envvar file, generated by `doom env refresh`. -This file contains environment variables scraped from your non and interactive -shell environment, and is loaded at startup (if it exist)s. This is helpful if -Emacs can't (easily) be launched from the correct shell session (particular for -MacOS users).") +This file contains environment variables scraped from your shell environment, +which is loaded at startup (if it exists). This is helpful if Emacs can't +(easily) be launched from the correct shell session (particularly for MacOS +users).") ;; ;;; Doom core variables (defvar doom-init-p nil - "Non-nil if `doom-initialize' has run.") + "Non-nil if Doom has been initialized.") (defvar doom-init-time nil - "The time it took, in seconds, for DOOM Emacs to initialize.") + "The time it took, in seconds, for Doom Emacs to initialize.") (defvar doom-emacs-changed-p nil "If non-nil, the running version of Emacs is different from the first time -Doom was setup, which can cause problems.") +Doom was setup, which may cause problems.") (defvar doom-site-load-path (cons doom-core-dir load-path) "The initial value of `load-path', before it was altered by @@ -251,9 +264,10 @@ original value of `symbol-file'." #'doom-try-run-hook)) (add-hook 'hack-local-variables-hook #'doom|run-local-var-hooks) +;; If `enable-local-variables' is disabled, then `hack-local-variables-hook' is +;; never triggered. (defun doom|run-local-var-hooks-if-necessary () - "If `enable-local-variables' is disabled, then `hack-local-variables-hook' is -never triggered." + "Run `doom|run-local-var-hooks' if `enable-local-variables' is disabled." (unless enable-local-variables (doom|run-local-var-hooks))) (add-hook 'after-change-major-mode-hook #'doom|run-local-var-hooks-if-necessary) @@ -265,7 +279,8 @@ never triggered." (defvar doom-incremental-packages '(t) "A list of packages to load incrementally after startup. Any large packages here may cause noticable pauses, so it's recommended you break them up into -sub-packages. For example, `org' is comprised of many packages, and can be broken up into: +sub-packages. For example, `org' is comprised of many packages, and can be +broken up into: (doom-load-packages-incrementally '(calendar find-func format-spec org-macs org-compat @@ -507,7 +522,7 @@ to least)." (doom-initialize noninteractive) (unless noninteractive (doom-initialize-modules)) -(after! package +(with-eval-after-load 'package (require 'core-packages) (doom-initialize-packages)) diff --git a/core/templates/QUICKSTART_INTRO b/core/templates/QUICKSTART_INTRO index bf3abef0e..8a410349e 100644 --- a/core/templates/QUICKSTART_INTRO +++ b/core/templates/QUICKSTART_INTRO @@ -1,9 +1,7 @@ Before you doom yourself, there are a few things you should know: -1. If you use GUI Emacs, run `M-x all-the-icons-install-fonts` so you don't get - weird symbols all over the place. - -2. Whenever you edit ~/.doom.d/init.el or modify modules, run: +1. Whenever you edit your doom! block in ~/.doom.d/init.el or modify your + modules, run: bin/doom refresh @@ -11,20 +9,17 @@ Before you doom yourself, there are a few things you should know: removed, and your autoloads files are up to date. This is important! If you forget to do this you will get errors! -3. If something inexplicably goes wrong, it's a good idea to try: - - bin/doom doctor +2. If something inexplicably goes wrong, try `bin/doom doctor` This will diagnose common issues with your environment and setup, and may give you clues about what is wrong. -4. To update doom, run +3. Use `bin/doom upgrade` to update Doom. Doing it any other way may require + additional work. When in doubt, run `bin/doom refresh`. - bin/doom upgrade +4. Check out `bin/doom help` to see what else `bin/doom` can do (and it is + recommended you add ~/.emacs.d/bin to your PATH). - Doing it any other way will require you run `bin/doom refresh` otherwise, - -5. Check out `bin/doom help` to see what else it can do (it is recommended you - add ~/.emacs.d/bin to your PATH). +5. You can find Doom's documentation via `M-x doom/help` or `SPC h D`. Have fun! diff --git a/modules/config/default/config.el b/modules/config/default/config.el index 71ea7555e..4d92bf507 100644 --- a/modules/config/default/config.el +++ b/modules/config/default/config.el @@ -111,7 +111,7 @@ ;; Highjacks backspace to: ;; a) balance spaces inside brackets/parentheses ( | ) -> (|) - ;; b) delete space-indented `tab-width' steps at a time + ;; b) delete up to nearest column multiple of `tab-width' at a time ;; c) close empty multiline brace blocks in one step: ;; { ;; | diff --git a/modules/lang/emacs-lisp/autoload.el b/modules/lang/emacs-lisp/autoload.el index e85c851ff..4798490a3 100644 --- a/modules/lang/emacs-lisp/autoload.el +++ b/modules/lang/emacs-lisp/autoload.el @@ -1,7 +1,7 @@ ;;; lang/emacs-lisp/autoload.el -*- lexical-binding: t; -*- ;; -;; Library +;;; Library ;;;###autoload (defun +emacs-lisp-eval (beg end) @@ -77,7 +77,7 @@ library/userland functions" ;; -;; Commands +;;; Commands ;;;###autoload (defun +emacs-lisp/open-repl () @@ -92,7 +92,7 @@ library/userland functions" ;; -;; Hooks +;;; Hooks ;;;###autoload (defun +emacs-lisp|extend-imenu () diff --git a/modules/lang/emacs-lisp/config.el b/modules/lang/emacs-lisp/config.el index c6b298019..0b198ead0 100644 --- a/modules/lang/emacs-lisp/config.el +++ b/modules/lang/emacs-lisp/config.el @@ -14,7 +14,7 @@ This marks a foldable marker for `outline-minor-mode' in elisp buffers.") ;; -;; Config +;;; Config (def-package! elisp-mode :mode ("\\.Cask\\'" . emacs-lisp-mode) @@ -76,14 +76,13 @@ This marks a foldable marker for `outline-minor-mode' in elisp buffers.") ;; -;; Packages +;;; Packages -;; `auto-compile' +;;;###package auto-compile (setq auto-compile-display-buffer nil auto-compile-use-mode-line nil) -;; `macrostep' (when (featurep! :editor evil) (after! macrostep (evil-define-key* 'normal macrostep-keymap @@ -108,7 +107,7 @@ This marks a foldable marker for `outline-minor-mode' in elisp buffers.") (add-hook 'macrostep-mode-hook #'evil-normalize-keymaps))) -;; `overseer' +;;;###package overseer (autoload 'overseer-test "overseer" nil t) (remove-hook 'emacs-lisp-mode-hook 'overseer-enable-mode) @@ -129,7 +128,7 @@ This marks a foldable marker for `outline-minor-mode' in elisp buffers.") ;; -;; Project modes +;;; Project modes (def-project-mode! +emacs-lisp-ert-mode :modes (emacs-lisp-mode) diff --git a/modules/lang/web/+css.el b/modules/lang/web/+css.el index ee987c085..8ef664c58 100644 --- a/modules/lang/web/+css.el +++ b/modules/lang/web/+css.el @@ -22,11 +22,12 @@ ;; -;; Major modes +;;; Major modes (add-hook! (css-mode sass-mode stylus-mode) #'rainbow-mode) -(after! css-mode ; built-in -- contains both css-mode & scss-mode +;; built-in, and contains both css-mode & scss-mode +(after! css-mode ;; css-mode hooks apply to scss and less-css modes (add-hook 'css-mode-hook #'rainbow-delimiters-mode) (unless EMACS26+ @@ -41,7 +42,7 @@ ;; -;; Tools +;;; Tools (when (featurep! +lsp) (add-hook! (css-mode sass-mode less-css-mode) #'lsp!)) diff --git a/modules/lang/web/autoload/css.el b/modules/lang/web/autoload/css.el index 93eacc2a0..2389af5b3 100644 --- a/modules/lang/web/autoload/css.el +++ b/modules/lang/web/autoload/css.el @@ -45,8 +45,9 @@ ;;;###autoload (defun +css/comment-indent-new-line () - "Continues the comment in an indented new line in css-mode and scss-mode. -Meant for `comment-line-break-function'." + "Continues the comment in an indented new line. + +Meant for `comment-line-break-function' in `css-mode' and `scss-mode'." (interactive) (when (sp-point-in-comment) (let ((at-end (looking-at-p ".+\\*/")) diff --git a/modules/lang/web/autoload/evil.el b/modules/lang/web/autoload/evil.el index c9a11f132..fcc563971 100644 --- a/modules/lang/web/autoload/evil.el +++ b/modules/lang/web/autoload/evil.el @@ -3,7 +3,7 @@ ;;;###autoload (autoload '+web:encode-html-entities "lang/web/autoload/evil" nil t) (evil-define-operator +web:encode-html-entities (beg end &optional input) - "Encodes HTML entities in the selected region." + "Encodes HTML entities in INPUT or the selected region." (interactive "") (cond (input (insert (+web-encode-entities input))) @@ -12,7 +12,7 @@ ;;;###autoload (autoload '+web:decode-html-entities "lang/web/autoload/evil" nil t) (evil-define-operator +web:decode-html-entities (beg end &optional input) - "Decodes HTML entities in the selected region." + "Decodes HTML entities in INPUT or the selected region." (interactive "") (cond (input (insert (+web-decode-entities input))) diff --git a/modules/lang/web/autoload/html.el b/modules/lang/web/autoload/html.el index cd9093fb5..cf205b79d 100644 --- a/modules/lang/web/autoload/html.el +++ b/modules/lang/web/autoload/html.el @@ -94,6 +94,10 @@ function @ http://ergoemacs.org/emacs/elisp_replace_html_entities_command.html" "TODO" (+web--entities-string text t)) + +;; +;;; Commands + ;;;###autoload (defun +web/encode-entities-region (beg end) "Encode HTML entities in region." @@ -108,8 +112,10 @@ function @ http://ergoemacs.org/emacs/elisp_replace_html_entities_command.html" ;;;###autoload (defun +web/indent-or-yas-or-emmet-expand () - "Invoke `indent-for-tab-command' if at or before text bol, `yas-expand' if on -a snippet, or `emmet-expand-yas'/`emmet-expand-line', depending on whether + "Do-what-I-mean on TAB. + +Invokes `indent-for-tab-command' if at or before text bol, `yas-expand' if on a +snippet, or `emmet-expand-yas'/`emmet-expand-line', depending on whether `yas-minor-mode' is enabled or not." (interactive) (call-interactively diff --git a/modules/tools/lookup/autoload/lookup.el b/modules/tools/lookup/autoload/lookup.el index ddf3f7cc1..d6361f8b6 100644 --- a/modules/tools/lookup/autoload/lookup.el +++ b/modules/tools/lookup/autoload/lookup.el @@ -5,10 +5,10 @@ ;;;###autodef (cl-defun set-lookup-handlers! (modes &rest plist &key definition references documentation file xref-backend async) - "Define a jump target for major MODES. + "Define jump handlers for major or minor MODES. This overwrites previously defined handlers for MODES. If used on minor modes, -they are combined with handlers defined for other minor modes or the major mode +they are stacked onto handlers defined for other minor modes or the major mode it's activated in. This can be passed nil as its second argument to unset handlers for MODES. e.g. @@ -33,10 +33,23 @@ Otherwise, these properties are available to be set: Defines an xref backend for a major-mode. If you define :definition and :references along with :xref-backend, those will have higher precedence. :async BOOL - Indicates that the supplied handlers *after* this property are asynchronous. - Note: async handlers do not fall back to the default handlers, due to their - nature. To get around this, you must write specialized wrappers to wait for - the async response and return 'fallback." + Indicates that *all* supplied FNs are asynchronous. Note: async handlers do + not fall back to the default handlers, due to their nature. To get around + this, you must write specialized wrappers to wait for the async response. + + If you only want to specify one FN is async, use a PLIST instead: + + (set-lookup-handlers! 'rust-mode + :definition '(racer-find-definition :async t)) + +Handlers can either be interactive or non-interactive. Non-interactive handlers +must take one argument: the identifier being looked up. This function must +change the current buffer or window or return non-nil when it succeeds. + +If it doesn't change the current buffer, or it returns nil, the lookup module +will fall back to the next handler in `+lookup-definition-functions', +`+lookup-references-functions', `+lookup-file-functions' or +`+lookup-documentation-functions'." (declare (indent defun)) (dolist (mode (doom-enlist modes)) (let ((hook (intern (format "%s-hook" mode))) @@ -60,7 +73,8 @@ Otherwise, these properties are available to be set: '+lookup-references-functions '+lookup-documentation-functions '+lookup-file-functions - 'xref-backend-functions))))) + 'xref-backend-functions) + async)))) (add-hook hook fn))))))