docs: minor revisions of docstrings across core+cli

bin/doom

@@ -165,10 +165,10 @@ EXIT CODES:
   3        Unrecognized user input error
   4        Command not found, or is incorrect/deprecated
   5        Invalid, missing, or extra options/arguments
-  6-49     Reserved for Doom
+  6-15     Reserved for Doom
-  50-200   Reserved for custom user codes
+  16-192   Reserved for the user's extensions
   254      Successful run (but then execute `doom-cli-restart-script')
-  255      Uncaught internal errors
+  255      Uncaught critical errors
 
 SEE ALSO:
   https://doomemacs.org               Homepage

lisp/cli/sync.el

@@ -36,14 +36,14 @@ This is the equivalent of running autoremove, install, autoloads, then
 recompile. Run this whenever you:
 
   1. Modify your `doom!' block,
-  2. Add or remove `package!' blocks to your config,
+  2. Add, remove, or modify `package!' blocks to your config,
-  3. Add or remove autoloaded functions in module autoloaded files,
+  3. Add, remove, or modify autoloaded functions in module autoloaded files,
-  4. Update Doom outside of Doom (e.g. with git),
+  4. Update Doom manually (e.g. with git),
   5. Move your Doom config (either $EMACSDIR or $DOOMDIR) to a new location.
-  6. When you up (or down) grade Emacs itself.
+  6. Up or downgrade Emacs itself (e.g. 29.1 -> 29.4).
 
-It will ensure that unneeded packages are removed, all needed packages are
+Sync'ing ensures that unneeded packages are removed, needed packages are
-installed, autoloads files are up-to-date and no byte-compiled files have gone
+installed, autoloads files are up-to-date, and no byte-compiled files have gone
 stale.
 
 OPTIONS:

lisp/doom.el

@@ -194,7 +194,7 @@
 ;;; Core globals
 
 (defgroup doom nil
-  "An Emacs framework for the stubborn martian hacker."
+  "A development framework for Emacs configurations and Emacs Lisp projects."
   :link '(url-link "https://doomemacs.org")
   :group 'emacs)
 
@@ -206,7 +206,7 @@
   "Current version of Doom Emacs.")
 
 (defvar doom-init-time nil
-  "The time it took, in seconds, for Doom Emacs to initialize.")
+  "The time it took, in seconds (as a float), for Doom Emacs to start up.")
 
 (defconst doom-profile
   (if-let (profile (getenv-internal "DOOMPROFILE"))
@@ -307,11 +307,11 @@ For profile-local cache files, use `doom-profile-cache-dir' instead.")
     (file-name-concat doom-local-dir "state/"))
   "Where Doom stores its global state files.
 
-State files contain unessential, unportable, but persistent data which, if lost
+State files contain unessential, non-portable, but persistent data which, if
-won't cause breakage, but may be inconvenient as they cannot be automatically
+lost won't cause breakage, but may be inconvenient as they cannot be
-regenerated or restored. For example, a recently-opened file list is not
+automatically regenerated or restored. For example, a recently-opened file list
-essential, but losing it means losing this record, and restoring it requires
+is not essential, but losing it means losing this record, and restoring it
-revisiting all those files.
+requires revisiting all those files.
 
 Use this for: history, logs, user-saved data, autosaves/backup files, known
 projects, recent files, bookmarks.
@@ -333,7 +333,7 @@ For profile-local state files, use `doom-profile-state-dir' instead.")
 
 (defconst doom-profile-dir
   (file-name-concat doom-profile-data-dir "@" (cdr doom-profile))
-  "Where generated files for the active profile are kept.")
+  "Where generated files for the active profile (for Doom's core) are kept.")
 
 ;; DEPRECATED: Will be moved to cli/env
 (defconst doom-env-file
@@ -536,14 +536,14 @@ empty. Each context describes what phase Doom is in, and may respond to.
 
 All valid contexts:
   cli        -- while executing a Doom CLI
-  compile    -- while byte-compilation is in progress
+  compile    -- while byte-compiling packages
-  eval       -- during inline evaluation of elisp
+  eval       -- during interactive evaluation of elisp
   init       -- while doom is formally starting up for the first time, after its
-                core libraries are loaded, but before user config is.
+                core libraries are loaded, but before $DOOMDIR is
-  modules    -- while loading modules and their files
+  modules    -- while loading modules configuration files (but not packages)
-  sandbox    -- This session was launched from Doom's sandbox.
+  sandbox    -- This session was launched from Doom's sandbox
-  packages   -- when packagedefs are being read
+  packages   -- while a module's packages.el's file is being evaluated
-  reload     -- while reloading doom")
+  reload     -- while reloading doom with `doom/reload'")
 (put 'doom-context 'valid-values '(cli compile eval init modules packages reload doctor sandbox))
 (put 'doom-context 'risky-local-variable t)
 
@@ -554,7 +554,9 @@ All valid contexts:
               (list context "Unrecognized context" valid)))))
 
 (defun doom-context-p (context)
-  "Return t if CONTEXT is active (i.e. in `doom-context')."
+  "Return t if CONTEXT is active, nil otherwise.
+
+See `doom-context' for possible values for CONTEXT."
   (if (memq context doom-context) t))
 
 (defun doom-context-push (context)