helpful

commit 582e167528628762fb8692cc841e3b0eba88ecdb
parent 5f126f1df6c96f744e43bc3b66e6d1cf766c16f3
Author: Wilfred Hughes <me@wilfred.me.uk>
Date:   Sat, 22 Jul 2017 12:36:44 +0100

Ensure the first line of the docstring is clearly separated

Diffstat:
M
helpful.el
 | 
15
++++++++++++++-
M
test/unit-test.el
 | 
14
++++++++++++++

2 files changed, 28 insertions(+), 1 deletion(-)
diff --git a/helpful.el b/helpful.el
@@ -194,6 +194,19 @@ This allows us to distinguish strings from symbols."
      'symbol sym)
     (buffer-string)))
 
+(defun helpful--split-first-line (docstring)
+  "If the first line is a standalone sentence, ensure we have a
+blank line afterwards."
+  (let* ((lines (s-lines docstring))
+         (first-line (-first-item lines))
+         (second-line (when (> (length lines) 1) (nth 1 lines))))
+    (if (and (s-ends-with-p "." first-line)
+             (stringp second-line)
+             (not (equal second-line "")))
+        (s-join "\n"
+                (-cons* first-line "" (cdr lines)))
+      docstring)))
+
 ;; TODO: fix upstream Emacs bug that means `-map' is not highlighted
 ;; in the docstring for `--map'.
 (defun helpful--format-docstring (docstring)
@@ -204,7 +217,7 @@ This allows us to distinguish strings from symbols."
      (let ((sym-name
             (s-chop-prefix "`" (s-chop-suffix "'" it))))
        (helpful--describe-button (read sym-name))))
-   docstring
+   (helpful--split-first-line docstring)
    t t))
 
 (defconst helpful--highlighting-funcs
diff --git a/test/unit-test.el b/test/unit-test.el
@@ -56,3 +56,17 @@
   (setplist #'test-foo-no-properties nil)
 
   (should (helpful-function #'test-foo-no-properties)))
+
+(ert-deftest helpful--split-first-line ()
+  ;; Don't modify a single line string.
+  (should
+   (equal (helpful--split-first-line "foo") "foo"))
+  ;; Don't modify a two-line string if we don't end with .
+  (should
+   (equal (helpful--split-first-line "foo\nbar") "foo\nbar"))
+  ;; If the second line is already empty, do nothing.
+  (should
+   (equal (helpful--split-first-line "foo.\n\nbar") "foo.\n\nbar"))
+  ;; But if we have a single sentence and no empy line, insert one.
+  (should
+   (equal (helpful--split-first-line "foo.\nbar") "foo.\n\nbar")))