Ensure backslashes in string literals are escaped

Fixes #197

3 files changed, 27 insertions, 8 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 77d9da0..26236f5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,9 @@ on their own line.
 Symbols of the form `foo-functions` (e.g. `after-change-functions`)
 are now rendered as hooks.
 
+String literals are now rendered correctly in docstrings. Previously
+command substitution applied inside literals.
+
 # v0.16
 
 Improved wording when looking at aliases.
diff --git a/helpful.el b/helpful.el
index ef5b66d..4aac2aa 100644
--- a/helpful.el
+++ b/helpful.el
@@ -969,15 +969,19 @@ unescaping too."
       (while (not (eobp))
         (cond
          ((looking-at
-           (rx "\""))
-          (looking-at
            ;; Text of the form "foo"
            (rx "\""))
-          ;; Don't do anything with literal strings.
-          ;; Step over opening doublequote.
-          (forward-char 1)
-          ;; Move past closing doublequote.
-          (search-forward "\""))
+          ;; For literal strings, escape backslashes so our output
+          ;; shows copy-pasteable literals.
+          (let* ((start-pos (point))
+                 (end-pos (progn (forward-char) (search-forward "\"" nil t)))
+                 contents)
+            (if end-pos
+                (progn
+                  (setq contents (buffer-substring start-pos end-pos))
+                  (delete-region start-pos end-pos)
+                  (insert (s-replace "\\" "\\\\" contents)))
+              (forward-char 1))))
          ((looking-at
            ;; Text of the form \=X
            (rx "\\="))
diff --git a/test/helpful-unit-test.el b/test/helpful-unit-test.el
index 3010708..d4fd835 100644
--- a/test/helpful-unit-test.el
+++ b/test/helpful-unit-test.el
@@ -71,13 +71,25 @@
 
 (ert-deftest helpful--docstring-strings ()
   "Double-quoted strings should be treated literally."
+  ;; Ensure backslashes are shown escaped, so the output is a valid string literal.
+  (let* ((formatted-docstring
+          (helpful--format-docstring
+           "hello \"x\\y\" world")))
+    ;; This test will fail in a local Emacs instance that has modified
+    ;; minibuffer keybindings.
+    (should
+     (string-equal formatted-docstring "hello \"x\\\\y\" world")))
+  ;; Don't crash on unbalanced doublequotes.
+  (helpful--format-docstring "hello \" world")
+  ;; Command sequences \\[foo] should be ignored inside doublequotes.
   (let* ((formatted-docstring
           (helpful--format-docstring
            "hello \"\\[foo]\" world")))
     ;; This test will fail in a local Emacs instance that has modified
     ;; minibuffer keybindings.
     (should
-     (string-equal formatted-docstring "hello \"\\[foo]\" world"))))
+     (string-equal formatted-docstring
+                   "hello \"\\\\[foo]\" world"))))
 
 (ert-deftest helpful--docstring-keymap ()
   "Handle keymap references in docstrings."