helpful

commit e3d8ee7fe4219d4172c3c9c0eddd4f3f9f051061
parent 69474e9c49076ce82cea4eff237933b6cec0b5cf
Author: Wilfred Hughes <me@wilfred.me.uk>
Date:   Tue, 13 Aug 2019 19:21:09 +0100

Use "and" in summaries

For example, say "ace-window is an autoloaded, interactive and
compiled function" rather than comma-separating everywhere.

Also simplify button logic and add a test for "an" in descriptions.

Diffstat:
M
helpful.el
 | 
55
++++++++++++++++++++++++++++++-------------------------
M
test/helpful-unit-test.el
 | 
11
+++++++++++

2 files changed, 41 insertions(+), 25 deletions(-)
diff --git a/helpful.el b/helpful.el
@@ -1775,6 +1775,18 @@ OBJ may be a symbol or a compiled function object."
   (and (symbolp sym)
        (byte-code-function-p (symbol-function sym))))
 
+(defun helpful--join-and (items)
+  "Join a list of strings with commas and \"and\"."
+  (cond
+   ((= (length items) 0)
+    "")
+   ((= (length items) 1)
+    (car items))
+   (t
+    (format "%s and %s"
+            (s-join ", " (-drop-last 1 items))
+            (-last-item items)))))
+
 (defun helpful--summary (sym callable-p buf pos)
   "Return a one sentence summary for SYM."
   (-let* ((primitive-p (helpful--primitive-p sym callable-p))
@@ -1827,30 +1839,16 @@ OBJ may be a symbol or a compiled function object."
            (and callable-p buf (helpful--autoloaded-p sym buf)))
           (compiled-p
            (and callable-p (helpful--compiled-p sym)))
+          (buttons
+           (list
+            (if alias-p alias-button)
+            (if (and callable-p autoloaded-p) autoload-button)
+            (if (and callable-p (commandp sym)) interactive-button)
+            (if compiled-p compiled-button)
+            (if (and (not callable-p) (local-variable-if-set-p sym))
+                buffer-local-button)))
           (description
-           (concat
-            (cond
-             (alias-p
-              (format "%s %s"
-                      (if callable-p "a" "an")
-                      alias-button))
-             ((and callable-p (commandp sym) autoloaded-p)
-              (format "an %s, %s" interactive-button autoload-button))
-             ((helpful--kbd-macro-p sym) "a")
-             ((and callable-p (commandp sym))
-              (format "an %s" interactive-button))
-             ((and callable-p autoloaded-p)
-              (format "an %s" autoload-button))
-             ((and (not callable-p)
-                   (local-variable-if-set-p sym))
-              (format "a %s" buffer-local-button))
-             (t
-              "a"))
-            (if compiled-p
-                (format "%s %s"
-                        (if (or (commandp sym) autoloaded-p) "," "")
-                        compiled-button))
-            ""))
+           (helpful--join-and (-non-nil buttons)))
           (kind
            (cond
             ((special-form-p sym)
@@ -1885,11 +1883,18 @@ OBJ may be a symbol or a compiled function object."
 
     (s-word-wrap
      70
-     (format "%s is %s %s %s."
+     (format "%s is %s %s %s %s."
              (if (symbolp sym)
                  (format "%S" sym)
                "This lambda")
-             description kind defined))))
+             (if (string-match-p
+                  (rx bos (or "a" "e" "i" "o" "u"))
+                  description)
+                 "an"
+               "a")
+             description
+             kind
+             defined))))
 
 (defun helpful--callees (form)
   "Given source code FORM, return a list of all the functions called."
diff --git a/test/helpful-unit-test.el b/test/helpful-unit-test.el
@@ -782,6 +782,17 @@ find the source code."
     (should
      (s-starts-with-p "if is a special form defined in" summary))))
 
+(defun helpful-test-fn-interactive ()
+  (interactive))
+
+(ert-deftest helpful--summary--interactive-fn ()
+  "Ensure we use \"an\" for interactive functions."
+  (let* ((summary (helpful--summary 'helpful-test-fn-interactive t nil nil)))
+    ;; Strip properties to make assertion messages more readable.
+    (set-text-properties 0 (1- (length summary)) nil summary)
+    (should
+     (s-starts-with-p "helpful-test-fn-interactive is an interactive function" summary))))
+
 (defun helpful-test-fn-with\ space ()
   42)