emacs: Support overriding help and describing prefix action

[notmuch] / emacs / notmuch.el

diff --git a/emacs/notmuch.el b/emacs/notmuch.el
index a36849f81fccc98197395443e1487e3955ad699e..278bd3560cdd5a04b68713ecdf16e76d7d8a60ee 100644 (file)
--- a/emacs/notmuch.el
+++ b/emacs/notmuch.el
@@ -140,7 +140,7 @@ This is basically just `format-kbd-macro' but we also convert ESC to M-."
        "M-"
       (concat desc " "))))
 
-(defun notmuch-describe-keymap (keymap &optional prefix tail)
+(defun notmuch-describe-keymap (keymap ua-keys &optional prefix tail)
   "Return a list of strings, each describing one key in KEYMAP.
 
 Each string gives a human-readable description of the key and the
@@ -151,10 +151,19 @@ first line of documentation for the bound function."
           ((keymapp binding)
            (setq tail
                  (notmuch-describe-keymap
-                  binding (notmuch-prefix-key-description key) tail)))
+                  binding ua-keys (notmuch-prefix-key-description key) tail)))
           (t
+           (when (and ua-keys (symbolp binding)
+                      (get binding 'notmuch-prefix-doc))
+             ;; Documentation for prefixed command
+             (let ((ua-desc (key-description ua-keys)))
+               (push (concat ua-desc " " prefix (format-kbd-macro (vector key))
+                             "\t" (get binding 'notmuch-prefix-doc))
+                     tail)))
+           ;; Documentation for command
            (push (concat prefix (format-kbd-macro (vector key)) "\t"
-                         (notmuch-documentation-first-line binding))
+                         (or (and (symbolp binding) (get binding 'notmuch-doc))
+                             (notmuch-documentation-first-line binding)))
                  tail))))
    keymap)
   tail)
@@ -165,14 +174,24 @@ first line of documentation for the bound function."
     (while (string-match "\\\\{\\([^}[:space:]]*\\)}" doc beg)
       (let* ((keymap-name (substring doc (match-beginning 1) (match-end 1)))
             (keymap (symbol-value (intern keymap-name)))
-            (desc-list (notmuch-describe-keymap keymap))
+            (ua-keys (where-is-internal 'universal-argument keymap t))
+            (desc-list (notmuch-describe-keymap keymap ua-keys))
             (desc (mapconcat #'identity desc-list "\n")))
        (setq doc (replace-match desc 1 1 doc)))
       (setq beg (match-end 0)))
     doc))
 
 (defun notmuch-help ()
-  "Display help for the current notmuch mode."
+  "Display help for the current notmuch mode.
+
+This is similar to `describe-function' for the current major
+mode, but bindings tables are shown with documentation strings
+rather than command names.  By default, this uses the first line
+of each command's documentation string.  A command can override
+this by setting the 'notmuch-doc property of its command symbol.
+A command that supports a prefix argument can explicitly document
+its prefixed behavior by setting the 'notmuch-prefix-doc property
+of its command symbol."
   (interactive)
   (let* ((mode major-mode)
         (doc (substitute-command-keys (notmuch-substitute-command-keys (documentation mode t)))))