Improve the raise-sexp doc string

* lisp/emacs-lisp/lisp.el (raise-sexp): Try to explain what the
command does (bug#55788).

1 files changed, 16 insertions, 1 deletions

diff --git a/lisp/emacs-lisp/lisp.el b/lisp/emacs-lisp/lisp.el
index ffca0dcf4f5..9d9ae41f301 100644
--- a/lisp/emacs-lisp/lisp.el
+++ b/lisp/emacs-lisp/lisp.el
@@ -858,7 +858,22 @@ The option `delete-pair-blink-delay' can disable blinking."
       (delete-char 1))))
 
 (defun raise-sexp (&optional arg)
-  "Raise ARG sexps higher up the tree."
+  "Raise ARG sexps higher up the tree.
+This means that the ARGth enclosing form will be deleted and
+replaced with the form that follows point.
+
+For instance, if you have:
+
+  (let ((foo 2))
+    (progn
+      (setq foo 3)
+      (zot)
+      (+ foo 2)))
+
+and point is before (zot), `M-x raise-sexp' will give you
+
+  (let ((foo 2))
+    (zot))"
   (interactive "p")
   (let ((s (if (and transient-mark-mode mark-active)
                (buffer-substring (region-beginning) (region-end))