helpful

commit 5911d3d642630455466a340e8633a7f62469b8cb
parent c8dd7c9eadb1bbfcf35c67104aa4f8715d632cee
Author: Wilfred Hughes <me@wilfred.me.uk>
Date:   Thu, 21 Dec 2017 23:11:46 +0000

Convert command keys references to buttons

Diffstat:
M
CHANGELOG.md
 | 
4
+++-
M
helpful.el
 | 
24
+++++++++++++++++++++++-
M
test/unit-test.el
 | 
10
++++++++++

3 files changed, 36 insertions(+), 2 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,7 +2,9 @@
 
 Allow function tracing to be enabled/disabled from Helpful buffers.
 
-Ensure docstring references to Info nodes are converted to buttons.
+Ensure docstring references to Info nodes are converted to
+buttons. Docstring references to command keys are converted to buttons
+too (see `set-mark-command` for an example).
 
 Helpful now shows all aliases for callables and variables, and
 highlights which aliases are obsolete.
diff --git a/helpful.el b/helpful.el
@@ -532,12 +532,34 @@ blank line afterwards."
    docstring
    t t))
 
+(defun helpful--propertize-command-keys (docstring)
+  "Convert command key references in docstrings to buttons."
+  (replace-regexp-in-string
+   ;; Replace all text of the form \\[foo] with a button that links to
+   ;; foo but shows the keys necessary to call foo.
+   (rx "\\["
+       (group (+ (not (in "]"))))
+       "]")
+   (lambda (it)
+     (let* ((symbol-with-parens (match-string 0 it))
+            (symbol-name (match-string 1 it))
+            (symbol (intern symbol-name)))
+       (helpful--button
+        ;; The button text should just be the keys required.
+        (substitute-command-keys symbol-with-parens)
+        'helpful-describe-exactly-button
+        'symbol symbol
+        'callable-p t)))
+   docstring
+   t t))
+
 ;; TODO: fix upstream Emacs bug that means `-map' is not highlighted
 ;; in the docstring for `--map'.
 (defun helpful--format-docstring (docstring)
   "Replace cross-references with links in DOCSTRING."
   (-> docstring
       (helpful--split-first-line)
+      (helpful--propertize-command-keys)
       (helpful--propertize-info)
       (helpful--propertize-symbols)
       (s-trim)))
@@ -1131,7 +1153,7 @@ For example, \"(some-func FOO &optional BAR)\"."
         docstring)
     (if callable-p
         (progn
-          (setq docstring (documentation sym))
+          (setq docstring (documentation sym t))
           (-when-let (docstring-with-usage (help-split-fundoc docstring sym))
             (setq docstring (cdr docstring-with-usage))
             (when docstring
diff --git a/test/unit-test.el b/test/unit-test.el
@@ -138,6 +138,16 @@
     ;; But we should always remove the backticks.
     (should (equal formatted "foo messagexxx."))))
 
+(ert-deftest helpful--format-docstring-command-keys ()
+  "Ensure we propertize references to command key sequences."
+  ;; This test will fail in your current Emacs instance if you've
+  ;; overridden the `set-mark-command' keybinding.
+  (-let [formatted (helpful--format-docstring "\\[set-mark-command]")]
+    (should
+     (string-equal formatted "C-SPC"))
+    (should
+     (get-text-property 0 'button formatted))))
+
 (setq helpful-var-without-defvar 'foo)
 
 (ert-deftest helpful--definition ()