helpful

commit b968411f42a8f923e80d609d4219d3d7362a2d03
parent 5eb8368c429833309abaa5c42e170e6fad84a19f
Author: Wilfred Hughes <me@wilfred.me.uk>
Date:   Sat, 20 Jan 2018 11:15:45 +0000

More robust `foo' handling in docstring highlighting

This fixes a number of issues spotted in the docstring of vhdl-mode.

Diffstat:
M
CHANGELOG.md
 | 
7
+++++++
M
helpful.el
 | 
30
++++++++++++++++++------------
M
test/unit-test.el
 | 
19
++++++++++++++++---

3 files changed, 41 insertions(+), 15 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,13 @@
 Fixed a crash on functions defined in a .elc when the .el file is not
 available.
 
+Better handling of docstrings:
+
+* All strings in quotes are highlighted. For example, previously
+  `` `C-M-\' `` was not highlighted because `C-M-\` doesn't look like
+  a symbol.
+* Handle nested key sequences correctly, such as `` `\\[foo]' ``.
+
 # v0.6
 
 Added imenu support! You can now navigate between headings with imenu.
diff --git a/helpful.el b/helpful.el
@@ -567,24 +567,30 @@ blank line afterwards."
    docstring
    t t))
 
-(defun helpful--propertize-symbols (docstring)
-  "Convert symbol references in docstrings to buttons."
+(defun helpful--propertize-quoted (docstring)
+  "Convert `foo' in docstrings to buttons (if bound) or else highlight."
   (replace-regexp-in-string
    ;; Replace all text of the form `foo'.
-   (rx "`" symbol-start (+? (not (any "`" "'"))) symbol-end "'")
+   (rx "`" (+? (not (any "`" "'"))) "'")
    (lambda (it)
      (let* ((sym-name
              (s-chop-prefix "`" (s-chop-suffix "'" it)))
             (sym (intern sym-name)))
-       ;; Only create a link if this is a symbol that is bound as a
-       ;; variable or callable.
-       (if (or (boundp sym) (fboundp sym))
-           (helpful--button
-            sym-name
-            'helpful-describe-button
-            'symbol sym)
+       (cond
+        ;; Only create a link if this is a symbol that is bound as a
+        ;; variable or callable.
+        ((or (boundp sym) (fboundp sym))
+         (helpful--button
+          sym-name
+          'helpful-describe-button
+          'symbol sym))
+        ;; If this is already a button, don't modify it.
+        ((get-text-property 0 'button sym-name)
+         sym-name)
+        ;; Highlight the quoted string.
+        (t
          (propertize sym-name
-                     'face 'font-lock-constant-face))))
+                     'face 'font-lock-constant-face)))))
    docstring
    t t))
 
@@ -675,8 +681,8 @@ unescaping too."
       (helpful--format-command-keys)
       (helpful--split-first-line)
       (helpful--propertize-info)
-      (helpful--propertize-symbols)
       (helpful--propertize-keywords)
+      (helpful--propertize-quoted)
       (s-trim)))
 
 (defconst helpful--highlighting-funcs
diff --git a/test/unit-test.el b/test/unit-test.el
@@ -155,7 +155,7 @@
     "(advice-add 'bar ...) 1 reference")))
 
 (ert-deftest helpful--format-docstring ()
-  "Ensure we create links in docstrings."
+  "Ensure we handle `foo' formatting correctly."
   ;; If it's bound, we should link it.
   (let* ((formatted (helpful--format-docstring "foo `message'."))
          (m-position (s-index-of "m" formatted)))
@@ -165,7 +165,11 @@
          (m-position (s-index-of "m" formatted)))
     (should (not (get-text-property m-position 'button formatted)))
     ;; But we should always remove the backticks.
-    (should (equal formatted "foo messagexxx."))))
+    (should (equal formatted "foo messagexxx.")))
+  ;; Don't require the text between the quotes to be a valid symbol, e.g.
+  ;; support `C-M-\' (found in `vhdl-mode').
+  (let* ((formatted (helpful--format-docstring "foo `C-M-\\'")))
+    (should (equal formatted "foo C-M-\\"))))
 
 (ert-deftest helpful--format-docstring-command-keys ()
   "Ensure we propertize references to command key sequences."
@@ -175,7 +179,16 @@
     (should
      (string-equal formatted "C-SPC"))
     (should
-     (get-text-property 0 'button formatted))))
+     (get-text-property 0 'button formatted)))
+  ;; If we have quotes around a key sequence, we should not propertize
+  ;; it as the button styling will no longer be visible.
+  (-let [formatted (helpful--format-docstring "`\\[set-mark-command]'")]
+    (should
+     (string-equal formatted "C-SPC"))
+    (should
+     (eq
+      (get-text-property 0 'face formatted)
+      'button))))
 
 (setq helpful-var-without-defvar 'foo)