Rewrite docstrings for package functions/macros
This commit is contained in:
Henrik Lissner
parent
ce5cd52642
commit
a002f7025c
2 changed files with 74 additions and 45 deletions
|
|
@ -5,7 +5,7 @@
|
|||
;; rolling-release, lazily-loaded package management system for Emacs.
|
||||
;;
|
||||
;; The three key commands are `doom/packages-install', `doom/packages-update'
|
||||
;; and `doom/packages-autoremove', which can be called via `make' on the command
|
||||
;; and `doom/packages-autoremove', which can be called via 'make' on the command
|
||||
;; line (make {install,update,autoremove}). These read packages.el files in each
|
||||
;; activated module in `doom-modules-dir' (and one in `doom-core-dir') which
|
||||
;; tell DOOM what plugins to install and where from.
|
||||
|
|
@ -15,7 +15,8 @@
|
|||
;; alternative to `list-packages' for updating and installing packages.
|
||||
;; 2. Flexibility: I want packages from sources other than ELPA. Primarily
|
||||
;; github, because certain plugins are out-of-date through official channels,
|
||||
;; have changed hands, or simply aren't in any ELPA repo.
|
||||
;; have changed hands, have a superior fork, or simply aren't in any ELPA
|
||||
;; repo.
|
||||
;; 3. Stability: I used Cask before this. It would error out with cyrptic errors
|
||||
;; depending on the version of Emacs I used and the alignment of the planets.
|
||||
;; No more.
|
||||
|
|
@ -293,8 +294,9 @@ Used by `require!' and `depends-on!'."
|
|||
(autoload 'use-package "use-package" nil nil 'macro)
|
||||
|
||||
(defmacro doom! (&rest modules)
|
||||
"DOOM Emacs bootstrap macro. List the modules to load. Benefits from
|
||||
byte-compilation."
|
||||
"Bootstrap DOOM Emacs.
|
||||
|
||||
MODULES is an malformed plist of modules to load."
|
||||
(doom-initialize-modules modules)
|
||||
(when (and user-login-name
|
||||
(not (doom-module-loaded-p :private (intern user-login-name))))
|
||||
|
|
@ -315,21 +317,29 @@ byte-compilation."
|
|||
(add-hook 'doom-init-hook #'doom--display-benchmark t))))
|
||||
|
||||
(defmacro def-package! (name &rest plist)
|
||||
"A thin wrapper around `use-package'."
|
||||
"A thin wrapper around `use-package'.
|
||||
|
||||
Ignores the package if its NAME is present in `doom-disabled-packages'."
|
||||
(when (and (memq name doom-disabled-packages)
|
||||
(not (memq :disabled plist)))
|
||||
(setq plist (append (list :disabled t) plist)))
|
||||
`(use-package ,name ,@plist))
|
||||
|
||||
(defmacro def-package-hook! (package when &rest body)
|
||||
"Configure a package using use-package hooks (see `use-package-inject-hooks').
|
||||
"Reconfigures a package's `def-package!' block.
|
||||
|
||||
PACKAGE is the package name.
|
||||
Under the hood, this uses use-package's `use-package-inject-hooks'.
|
||||
|
||||
PACKAGE is a symbol; the package's name.
|
||||
WHEN should be one of the following:
|
||||
:pre-init :post-init :pre-config :post-config
|
||||
:pre-init :post-init :pre-config :post-config :disable
|
||||
|
||||
WHEN can also be :disable (then BODY is ignored), which will instruct DOOM to
|
||||
ignore any `def-package!' blocks for PACKAGE."
|
||||
If WHEN is :disable then BODY is ignored, and DOOM will be instructed to ignore
|
||||
all `def-package!' blocks for PACKAGE.
|
||||
|
||||
WARNING: If :pre-init or :pre-config hooks return nil, the original
|
||||
`def-package!''s :init/:config block (respectively) is overwritten, so remember
|
||||
to have them return non-nil (or exploit that to overwrite Doom's config)."
|
||||
(declare (indent defun))
|
||||
(cond ((eq when :disable)
|
||||
(push package doom-disabled-packages)
|
||||
|
|
@ -374,8 +384,9 @@ If NOERROR is non-nil, don't throw an error if the file doesn't exist."
|
|||
(error "Could not load! file %s" file))))))
|
||||
|
||||
(defmacro require! (module submodule &optional reload-p)
|
||||
"Like `require', but for doom modules. Will load a module's config.el file if
|
||||
it hasn't already, and if it exists."
|
||||
"Loads the module specified by MODULE (a property) and SUBMODULE (a symbol).
|
||||
|
||||
The module is only loaded once. If RELOAD-P is non-nil, load it again."
|
||||
(let ((loaded-p (doom-module-loaded-p module submodule)))
|
||||
(when (or reload-p (not loaded-p))
|
||||
(unless loaded-p
|
||||
|
|
@ -388,7 +399,7 @@ it hasn't already, and if it exists."
|
|||
(car ex) ,module ',submodule (error-message-string ex)))))))
|
||||
|
||||
(defmacro featurep! (module submodule)
|
||||
"Convenience macro that wraps `doom-module-loaded-p'."
|
||||
"Convenience macro wrapper for `doom-module-loaded-p'."
|
||||
(doom-module-loaded-p module submodule))
|
||||
|
||||
|
||||
|
|
@ -397,8 +408,13 @@ it hasn't already, and if it exists."
|
|||
;;
|
||||
|
||||
(defmacro package! (name &rest plist)
|
||||
"Declares a package and how to install it (if applicable). This does not load
|
||||
nor install them.
|
||||
"Declares a package and how to install it (if applicable).
|
||||
|
||||
This macro is declarative and does not load nor install packages. It is used to
|
||||
populate `doom-packages' with metadata about the packages Doom needs to keep
|
||||
track of.
|
||||
|
||||
Only use this macro in a module's packages.el file.
|
||||
|
||||
Accepts the following properties:
|
||||
|
||||
|
|
@ -407,12 +423,8 @@ Accepts the following properties:
|
|||
from external sources.
|
||||
:pin ARCHIVE-NAME Instructs ELPA to only look for this package in
|
||||
ARCHIVE-NAME. e.g. \"org\". Ignored if RECIPE is present.
|
||||
:ignore t Do not install this package.
|
||||
:freeze t Do not update this package.
|
||||
|
||||
This macro serves a purely declarative purpose, and are used to fill
|
||||
`doom-packages', so that functions like `doom/packages-install' can operate on
|
||||
them."
|
||||
:ignore FORM Do not install this package if FORM is non-nil.
|
||||
:freeze FORM Do not update this package if FORM is non-nil."
|
||||
(declare (indent defun))
|
||||
(let* ((old-plist (assq name doom-packages))
|
||||
(pkg-recipe (or (plist-get plist :recipe)
|
||||
|
|
@ -436,8 +448,12 @@ them."
|
|||
(push ',(cons name plist) doom-packages))))
|
||||
|
||||
(defmacro depends-on! (module submodule)
|
||||
"Declares that this module depends on another. MODULE is a keyword, and
|
||||
SUBMODULE is a symbol."
|
||||
"Declares that this module depends on another.
|
||||
|
||||
Only use this macro in a module's packages.el file.
|
||||
|
||||
MODULE is a keyword, and SUBMODULE is a symbol. Under the hood, this simply
|
||||
loads MODULE SUBMODULE's packages.el file."
|
||||
(doom--enable-module module submodule)
|
||||
`(load! packages ,(doom-module-path module submodule) t))
|
||||
|
||||
|
|
@ -447,10 +463,14 @@ SUBMODULE is a symbol."
|
|||
;;
|
||||
|
||||
(defun doom/reload ()
|
||||
"Reload `load-path' and recompile files (if necessary). Useful if you
|
||||
modify/update packages outside of emacs. Automatically called (through the
|
||||
server, if necessary) by `doom/packages-install', `doom/packages-update' and
|
||||
`doom/packages-autoremove'. "
|
||||
"Reload `load-path' and recompile files (if necessary).
|
||||
|
||||
Use this when `load-path' is out of sync with your plugins. This should only
|
||||
happen if you manually modify/update/install packages from outside Emacs, while
|
||||
an Emacs session is running.
|
||||
|
||||
This isn't necessary if you use Doom's package management commands because they
|
||||
call `doom/reload' remotely (through emacsclient)."
|
||||
(interactive)
|
||||
(cond (noninteractive
|
||||
(message "Reloading...")
|
||||
|
|
@ -466,14 +486,15 @@ server, if necessary) by `doom/packages-install', `doom/packages-update' and
|
|||
(run-hooks 'doom-reload-hook))))
|
||||
|
||||
(defun doom/reload-autoloads ()
|
||||
"Refreshes the autoloads.el file, which tells Emacs where to find all the
|
||||
autoloaded functions in enabled modules or among the core libraries, e.g.
|
||||
core/autoload/*.el.
|
||||
"Refreshes the autoloads.el file, specified by `doom-autoload-file'.
|
||||
|
||||
In modules, checks modules/*/autoload.el and modules/*/autoload/*.el.
|
||||
It scans and reads core/autoload/*.el, modules/*/*/autoload.el and
|
||||
modules/*/*/autoload/*.el, and generates an autoloads file at the path specified
|
||||
by `doom-autoload-file'. This file tells Emacs where to find lazy-loaded
|
||||
functions.
|
||||
|
||||
Rerun this whenever init.el is modified. You can also use `make autoloads` from
|
||||
the commandline."
|
||||
This should be run whenever init.el or an autoload file is modified. Running
|
||||
'make autoloads' from the commandline executes this command."
|
||||
(interactive)
|
||||
;; This function must not use autoloaded functions or external dependencies.
|
||||
;; It must assume nothing is set up!
|
||||
|
|
@ -525,12 +546,18 @@ the commandline."
|
|||
(kill-buffer buf)))))
|
||||
|
||||
(defun doom/compile (&optional lite-p only-recompile-p)
|
||||
"Byte compile your emacs configuration (init.el, core/*.el &
|
||||
modules/*/*/**.el). DOOM Emacs was designed to benefit from this, but it may
|
||||
take a while.
|
||||
"Byte compiles your emacs configuration.
|
||||
|
||||
If LITE-P is non-nil, only compile the essential, core DOOM files (init.el &
|
||||
core/**/*.el).
|
||||
Specifically, this byte-compiles init.el, core/*.el, core/autoload/*.el &
|
||||
modules/*/*/**.el. It ignores unit tests and files with `no-byte-compile'
|
||||
enabled.
|
||||
|
||||
DOOM Emacs was designed to benefit from byte-compilation, but the process may
|
||||
take a while. Also, while your config files are byte-compiled, changes to them
|
||||
will not take effect! Use `doom/clean-compiled' or `make clean' to undo
|
||||
byte-compilation.
|
||||
|
||||
If LITE-P is non-nil, only compile the core DOOM files (init.el & core/**/*.el).
|
||||
|
||||
If ONLY-RECOMPILE-P is non-nil, only recompile out-of-date files."
|
||||
(interactive "P")
|
||||
|
|
@ -584,22 +611,24 @@ If ONLY-RECOMPILE-P is non-nil, only recompile out-of-date files."
|
|||
(format "(%s ignored)" total-nocomp)))))))
|
||||
|
||||
(defun doom/recompile ()
|
||||
"Recompile any compiled *.el files in your Emacs configuration."
|
||||
"Recompile any out-of-date compiled *.el files in your Emacs configuration."
|
||||
(interactive)
|
||||
(doom/compile nil :recompile)
|
||||
;; In case `load-path' has changed (e.g. after an update)
|
||||
(byte-recompile-file (expand-file-name "core.el" doom-core-dir) t))
|
||||
|
||||
(defun doom/clean-cache ()
|
||||
"Clear local cache (`doom-cache-dir'). You may need to restart Emacs for some
|
||||
components to feel its effects."
|
||||
"Clear the local cache completely (in `doom-cache-dir').
|
||||
|
||||
You must restart Emacs for some components to feel its effects."
|
||||
(interactive)
|
||||
(delete-directory doom-cache-dir t)
|
||||
(make-directory doom-cache-dir t))
|
||||
|
||||
(defun doom/clean-compiled ()
|
||||
"Delete all compiled elc files in DOOM emacs, excluding compiled ELPA/QUELPA
|
||||
package files."
|
||||
"Delete all compiled elc files in your Emacs configuration.
|
||||
|
||||
This excludes compiled packages in `doom-packages-dir'."
|
||||
(interactive)
|
||||
(let ((targets (append (list (expand-file-name "init.elc" doom-emacs-dir))
|
||||
(directory-files-recursively doom-core-dir "\\.elc$")
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue