From 98a3cad54d1a14978c1bd6570ded8c4136b5fd19 Mon Sep 17 00:00:00 2001
From: Henrik Lissner <git@henrik.io>
Date: Thu, 18 Jul 2024 22:34:25 -0400
Subject: [PATCH] docs: minor docstring revisions

For clarity only. These do not reflect any recent changes.
---
 lisp/cli/upgrade.el   | 12 ++++++------
 lisp/doom-packages.el |  4 ++--
 lisp/lib/config.el    |  3 +++
 3 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/lisp/cli/upgrade.el b/lisp/cli/upgrade.el
index c44b300e9..67f9f9897 100644
--- a/lisp/cli/upgrade.el
+++ b/lisp/cli/upgrade.el
@@ -23,14 +23,14 @@
      (jobs       ("-j" "--jobs" num) "How many CPUs to use for native compilation")
      (nobuild?   ("-B") "Don't rebuild packages when hostname or Emacs version has changed")
      &context context)
-  "Updates Doom and packages.
+  "Updates Doom's core, module libraries, and installed packages.
 
-This requires that ~/.emacs.d is a git repo, and is the equivalent of the
-following shell commands:
+A convenience command for updating Doom's core and pinned modules/module
+libraries. It is the equivalent of the following shell commands:
 
-    cd ~/.emacs.d
-    git pull --rebase
-    doom sync -u"
+    $ cd ~/.emacs.d
+    $ git pull --rebase
+    $ doom sync -u"
   (let* ((force? (doom-cli-context-suppress-prompts-p context))
          (sync-cmd (append '("sync" "-u")
                            (if nobuild? '("-B"))
diff --git a/lisp/doom-packages.el b/lisp/doom-packages.el
index 90ffb5154..5a6cb7e4e 100644
--- a/lisp/doom-packages.el
+++ b/lisp/doom-packages.el
@@ -606,8 +606,8 @@ Only use this macro in a module's (or your private) packages.el file."
 (defmacro unpin! (&rest targets)
   "Unpin packages in TARGETS.
 
-This unpins packages, so that 'doom upgrade' downloads their latest version. It
-can be used one of five ways:
+This unpins packages, so that `doom upgrade' or `doom sync -u' will update them
+to the latest commit available. Some examples:
 
 - To disable pinning wholesale: (unpin! t)
 - To unpin individual packages: (unpin! packageA packageB ...)
diff --git a/lisp/lib/config.el b/lisp/lib/config.el
index 915c764fc..8fe468919 100644
--- a/lisp/lib/config.el
+++ b/lisp/lib/config.el
@@ -73,6 +73,9 @@ And jumps to your `doom!' block."
 (defun doom/reload ()
   "Reloads your private config.
 
+WARNING: This command is experimental! If you haven't configured your config to
+be idempotent, then this could cause compounding slowness or errors.
+
 This is experimental! It will try to do as `bin/doom sync' does, but from within
 this Emacs session. i.e. it reload autoloads files (if necessary), reloads your
 package list, and lastly, reloads your private config.el.