docs: minor docstring revisions

For clarity only. These do not reflect any recent changes.

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"))

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 ...)

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.