emacs-29 a365984d9e1 2/2: package-upgrade[-all]: Expand docstrings to note the current limitation

[Dmitry Gutov]

branch: emacs-29
commit a365984d9e167c4d71a2a44a1abb4710765f460f
Author: Dmitry Gutov <dmitry@gutov.dev>
Commit: Dmitry Gutov <dmitry@gutov.dev>

    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).
---
 lisp/emacs-lisp/package.el | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/lisp/emacs-lisp/package.el b/lisp/emacs-lisp/package.el
index e15536c9f50..74796fc8744 100644
--- 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)))