emacs-29 d9e43f2197f: Document changes in 'edmacro-parse-keys'

[Eli Zaretskii]

branch: emacs-29
commit d9e43f2197fa1d5ade1d483b15cc50c6d705b969
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Document changes in 'edmacro-parse-keys'
    
    * lisp/edmacro.el (edmacro-parse-keys): Add a comment for forcing
    output to be a vector.
    (read-kbd-macro): Adjust the doc string to changes in
    'edmacro-parse-keys'.  (Bug#67182)
---
 lisp/edmacro.el | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/lisp/edmacro.el b/lisp/edmacro.el
index 0b62bf262bc..535c50cee84 100644
--- a/lisp/edmacro.el
+++ b/lisp/edmacro.el
@@ -228,14 +228,14 @@ With a prefix argument, format the macro in a more 
concise way."
 ;;;###autoload
 (defun read-kbd-macro (start &optional end)
   "Read the region as a keyboard macro definition.
-The region is interpreted as spelled-out keystrokes, e.g., \"M-x abc RET\".
-See documentation for `edmacro-mode' for details.
+The region between START and END is interpreted as spelled-out keystrokes,
+e.g., \"M-x abc RET\".  See documentation for `edmacro-mode' for details.
 Leading/trailing \"C-x (\" and \"C-x )\" in the text are allowed and ignored.
 The resulting macro is installed as the \"current\" keyboard macro.
 
 In Lisp, may also be called with a single STRING argument in which case
 the result is returned rather than being installed as the current macro.
-The result will be a string if possible, otherwise an event vector.
+The result is a vector of input events.
 Second argument NEED-VECTOR means to return an event vector always."
   (interactive "r")
   (if (stringp start)
@@ -672,6 +672,13 @@ This function assumes that the events can be stored in a 
string."
 
 (defun edmacro-parse-keys (string &optional _need-vector)
   (let ((result (kbd string)))
+    ;; Always return a vector.  Stefan Monnier <monnier@iro.umontreal.ca>
+    ;; writes: "I want to eliminate the use of strings that stand for a
+    ;; sequence of events because it does nothing more than leave latent
+    ;; bugs and create confusion (between the strings used as input to
+    ;; `read-kbd-macro' and the strings that used to be output by
+    ;; `read-kbd-macro'), while increasing the complexity of the rest of
+    ;; the code which has to handle both vectors and strings."
     (if (stringp result)
         (seq-into result 'vector)
       result)))