Handle keymap references in docstrings

Fixes #83.

3 files changed, 59 insertions, 37 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4c80085..2cfbba5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,7 @@ Smarter handling of keybindings:
   that inherit them.
 * Don't show menu bar items, as they clutter the display (please file
   a bug if you miss this).
+* Correctly handle `\<foo-map>` in docstrings.
 
 # v0.5
 
diff --git a/helpful.el b/helpful.el
index 397f490..44c8088 100644
--- a/helpful.el
+++ b/helpful.el
@@ -606,43 +606,54 @@ Emacs uses \\= to escape \\[ references, so replace that
 unescaping too."
   ;; Based on `substitute-command-keys', but converts command
   ;; references to buttons.
-  (with-temp-buffer
-    (insert docstring)
-    (goto-char (point-min))
-    (while (not (eobp))
-      (cond
-       ((looking-at
-         ;; Text of the form \=X
-         (rx "\\="))
-        ;; Remove the escaping, then step over the escaped char.
-        ;; Step over the escaped character.
-        (delete-region (point) (+ (point) 2))
-        (forward-char 1))
-       ((looking-at
-         ;; Text of the form \\[foo]
-         (rx "\\[" (group (+ (not (in "]")))) "]"))
-        (let* ((symbol-with-parens (match-string 0))
-               (symbol-name (match-string 1)))
-          ;; Remove the original string.
-          (delete-region (point)
-                         (+ (point) (length symbol-with-parens)))
-          ;; Add a button.
-          (let* ((symbol (intern symbol-name))
-                 (key (where-is-internal symbol nil t))
-                 (key-description
-                  (if key
-                      (key-description key)
-                    (format "M-x %s" symbol-name))))
-            (insert
-             (helpful--button
-              key-description
-              'helpful-describe-exactly-button
-              'symbol symbol
-              'callable-p t)))))
-       ;; Don't modify other characters.
-       (t
-        (forward-char 1))))
-    (buffer-string)))
+  (let ((keymap nil))
+    (with-temp-buffer
+      (insert docstring)
+      (goto-char (point-min))
+      (while (not (eobp))
+        (cond
+         ((looking-at
+           ;; Text of the form \=X
+           (rx "\\="))
+          ;; Remove the escaping, then step over the escaped char.
+          ;; Step over the escaped character.
+          (delete-region (point) (+ (point) 2))
+          (forward-char 1))
+         ((looking-at
+           ;; Text of the form \\<foo-keymap>
+           (rx "\\<" (group (+ (not (in ">")))) ">"))
+          (let* ((symbol-with-parens (match-string 0))
+                 (symbol-name (match-string 1)))
+            ;; Remove the original string.
+            (delete-region (point)
+                           (+ (point) (length symbol-with-parens)))
+            ;; Set the new keymap.
+            (setq keymap (symbol-value (intern symbol-name)))))
+         ((looking-at
+           ;; Text of the form \\[foo-command]
+           (rx "\\[" (group (+ (not (in "]")))) "]"))
+          (let* ((symbol-with-parens (match-string 0))
+                 (symbol-name (match-string 1)))
+            ;; Remove the original string.
+            (delete-region (point)
+                           (+ (point) (length symbol-with-parens)))
+            ;; Add a button.
+            (let* ((symbol (intern symbol-name))
+                   (key (where-is-internal symbol keymap t))
+                   (key-description
+                    (if key
+                        (key-description key)
+                      (format "M-x %s" symbol-name))))
+              (insert
+               (helpful--button
+                key-description
+                'helpful-describe-exactly-button
+                'symbol symbol
+                'callable-p t)))))
+         ;; Don't modify other characters.
+         (t
+          (forward-char 1))))
+      (buffer-string))))
 
 ;; TODO: fix upstream Emacs bug that means `-map' is not highlighted
 ;; in the docstring for `--map'.
diff --git a/test/unit-test.el b/test/unit-test.el
index 51029da..db75500 100644
--- a/test/unit-test.el
+++ b/test/unit-test.el
@@ -34,6 +34,16 @@
     (should
      (not (s-contains-p "\\=" formatted-docstring)))))
 
+(ert-deftest helpful--docstring-keymap ()
+  "Handle keymap references in docstrings."
+  (let* ((formatted-docstring
+          (helpful--format-docstring
+           "\\<minibuffer-local-map>\\[next-history-element]")))
+    ;; This test will fail in a local Emacs instance that has modified
+    ;; minibuffer keybindings.
+    (should
+     (string-equal formatted-docstring "M-n"))))
+
 (ert-deftest helpful--docstring-advice ()
   "Get the docstring on advised functions."
   (should