Rewrite docstrings for package functions/macros

core/autoload/packages.el

@@ -262,8 +262,8 @@ example; the package name can be omitted)."
       t)))
 
 (defun doom-update-package (name &optional force-p)
-  "Updates package NAME if it is out of date, using quelpa or package.el as
+  "Updates package NAME (a symbol) if it is out of date, using quelpa or
-appropriate."
+package.el as appropriate."
   (doom-initialize)
   (unless (package-installed-p name)
     (user-error "%s isn't installed" name))

core/core-packages.el

@@ -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
+  "Bootstrap DOOM Emacs.
-byte-compilation."
+
+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
+If WHEN is :disable then BODY is ignored, and DOOM will be instructed to ignore
-ignore any `def-package!' blocks for PACKAGE."
+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
+  "Loads the module specified by MODULE (a property) and SUBMODULE (a symbol).
-it hasn't already, and if it exists."
+
+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
+  "Declares a package and how to install it (if applicable).
-nor install them.
+
+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.
+ :ignore FORM          Do not install this package if FORM is non-nil.
- :freeze t             Do not update this package.
+ :freeze FORM          Do not update this package if FORM is non-nil."
-
-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."
   (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
+  "Declares that this module depends on another.
-SUBMODULE is a symbol."
+
+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
+  "Reload `load-path' and recompile files (if necessary).
-modify/update packages outside of emacs. Automatically called (through the
+
-server, if necessary) by `doom/packages-install', `doom/packages-update' and
+Use this when `load-path' is out of sync with your plugins. This should only
-`doom/packages-autoremove'. "
+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
+  "Refreshes the autoloads.el file, specified by `doom-autoload-file'.
-autoloaded functions in enabled modules or among the core libraries, e.g.
-core/autoload/*.el.
 
-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
+This should be run whenever init.el or an autoload file is modified. Running
-the commandline."
+'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 &
+  "Byte compiles your emacs configuration.
-modules/*/*/**.el). DOOM Emacs was designed to benefit from this, but it may
-take a while.
 
-If LITE-P is non-nil, only compile the essential, core DOOM files (init.el &
+Specifically, this byte-compiles init.el, core/*.el, core/autoload/*.el &
-core/**/*.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
+  "Clear the local cache completely (in `doom-cache-dir').
-components to feel its effects."
+
+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
+  "Delete all compiled elc files in your Emacs configuration.
-package files."
+
+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$")