package-upgrade[-all]: Expand docstrings to note the current limitation

* lisp/emacs-lisp/package.el (package-upgrade, package-upgrade-all):
Expand docstrings to note the current limitation (bug#62720).

diff --git a/lisp/emacs-lisp/package.el b/lisp/emacs-lisp/package.el
index e15536c9f508e00b2a07740fbdcd56e24d964606..74796fc8744de31249aa5520e8a524aeabe97e59 100644 (file)
--- a/lisp/emacs-lisp/package.el
+++ b/lisp/emacs-lisp/package.el
@@ -2267,7 +2267,11 @@ had been enabled."
 
 ;;;###autoload
 (defun package-upgrade (name)
-  "Upgrade package NAME if a newer version exists."
+  "Upgrade package NAME if a newer version exists.
+
+Currently, packages which are part of the Emacs distribution
+cannot be upgraded that way.  Use `i' after `M-x list-packages' to
+upgrade to an ELPA version first."
   (interactive
    (list (completing-read
           "Upgrade package: " (package--upgradeable-packages) nil t)))
@@ -2301,7 +2305,11 @@ had been enabled."
 (defun package-upgrade-all (&optional query)
   "Refresh package list and upgrade all packages.
 If QUERY, ask the user before upgrading packages.  When called
-interactively, QUERY is always true."
+interactively, QUERY is always true.
+
+Currently, packages which are part of the Emacs distribution are
+not upgraded that way.  Use `i' after `M-x list-packages' to
+upgrade to an ELPA version first."
   (interactive (list (not noninteractive)))
   (package-refresh-contents)
   (let ((upgradeable (package--upgradeable-packages)))