Function: describe-key

describe-key is an interactive and byte-compiled function defined in help.el.gz.

Signature

(describe-key KEY-LIST &optional BUFFER)

Documentation

Display documentation of the function invoked by KEY-LIST.

KEY-LIST can be any kind of a key sequence; it can include keyboard events, mouse events, and/or menu events. When calling from a program, pass KEY-LIST as a list of elements (SEQ . RAW-SEQ) where SEQ is a key-sequence and RAW-SEQ is its untranslated form.

While reading KEY-LIST interactively, this command temporarily enables menu items or tool-bar buttons that are disabled to allow getting help on them.

Interactively, this command can't describe prefix commands, but will always wait for the user to type the complete key sequence. For instance, entering "C-x" will wait until the command has been completed, but M-: (describe-key (kbd "C-x")) RET will tell you what this prefix command is bound to.

BUFFER is the buffer in which to lookup those keys; it defaults to the current buffer.

View in manual

Probably introduced at or before Emacs version 22.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/help.el.gz
(defun describe-key (&optional key-list buffer up-event)
  "Display documentation of the function invoked by KEY-LIST.
KEY-LIST can be any kind of a key sequence; it can include keyboard events,
mouse events, and/or menu events.  When calling from a program,
pass KEY-LIST as a list of elements (SEQ . RAW-SEQ) where SEQ is
a key-sequence and RAW-SEQ is its untranslated form.

While reading KEY-LIST interactively, this command temporarily enables
menu items or tool-bar buttons that are disabled to allow getting help
on them.

Interactively, this command can't describe prefix commands, but
will always wait for the user to type the complete key sequence.
For instance, entering \"C-x\" will wait until the command has
been completed, but `M-: (describe-key (kbd \"C-x\")) RET' will
tell you what this prefix command is bound to.

BUFFER is the buffer in which to lookup those keys; it defaults to the
current buffer."
  (declare (advertised-calling-convention (key-list &optional buffer) "27.1"))
  (interactive (list (help--read-key-sequence)))
  (when (arrayp key-list)
    ;; Compatibility with old calling convention.
    (setq key-list (cons (list key-list) (if up-event (list up-event))))
    (when buffer
      (let ((raw (if (numberp buffer) (this-single-command-raw-keys) buffer)))
        (setf (cdar (last key-list)) raw)))
    (setq buffer nil))
  (let* ((help-buffer-under-preparation t)
         (buf (or buffer (current-buffer)))
         (describe-function-orig-buffer buf)
         (on-link
          (mapcar (lambda (kr)
                    (let ((raw (cdr kr)))
                      (and (not (memq mouse-1-click-follows-link '(nil double)))
                           (> (length raw) 0)
                           (eq (car-safe (aref raw 0)) 'mouse-1)
                           (with-current-buffer buf
                             (mouse-on-link-p (event-start (aref raw 0)))))))
                  key-list))
         (info-list
          (help--filter-info-list
           (with-current-buffer buf
             (mapcar (lambda (x)
                       (pcase-let* ((`(,seq . ,raw-seq) x)
                                    (`(,brief-desc ,defn ,event ,_mouse-msg)
                                     (help--analyze-key seq raw-seq buffer))
                                    (locus
                                     (help--binding-locus
                                      seq (event-start event))))
                         `(,seq ,brief-desc ,defn ,locus)))
                     key-list))
           2)))
    (help-setup-xref (list #'describe-key--helper key-list buf)
		     (called-interactively-p 'interactive))
    (if (and (<= (length info-list) 1)
             (help--binding-undefined-p (nth 2 (car info-list))))
        (message "%s" (nth 1 (car info-list)))
      (with-help-window (help-buffer)
        (when (> (length info-list) 1)
          ;; FIXME: Make this into clickable hyperlinks.
          (insert "There were several key-sequences:\n\n")
          (insert (mapconcat (lambda (info)
                               (pcase-let ((`(,_seq ,brief-desc ,_defn ,_locus)
                                            info))
                                 (concat "  " brief-desc)))
                             info-list
                             "\n"))
          (when (delq nil on-link)
            (insert "\n\nThose are influenced by `mouse-1-click-follows-link'"))
          (insert "\n\nThey're all described below."))
        (pcase-dolist (`(,_seq ,brief-desc ,defn ,locus)
                       info-list)
          (when defn
            (when (> (length info-list) 1)
              (with-current-buffer standard-output
                (insert "\n\n" (make-separator-line) "\n")))

            (insert brief-desc)
            (when locus
              (insert (format " (found in %s)" locus)))
            (insert ", which is ")
	    (describe-function-1 defn)))))))