Fix pluralization in shortdoc-help-fns-examples-function

* lisp/emacs-lisp/shortdoc.el (shortdoc-help-fns-examples-function):
Implement a better logic to pluralize "Example", by counting the
number of arrow characters in the example string. (Bug#61877)
* test/lisp/emacs-lisp/shortdoc-tests.el
(shortdoc-help-fns-examples-function-test): Add a test.

diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 6e3ebc7c6a210e905fad2a1e834eec5200b96e19..9a6f5dd12ce902a164a54abce9ea13bf16990c03 100644 (file)
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -1621,13 +1621,38 @@ doesn't has any shortdoc information."
 You can add this function to the `help-fns-describe-function-functions'
 hook to show examples of using FUNCTION in *Help* buffers produced
 by \\[describe-function]."
-  (let ((examples (shortdoc-function-examples function))
-        (times 0))
+  (let* ((examples (shortdoc-function-examples function))
+         (num-examples (length examples))
+         (times 0))
     (dolist (example examples)
       (when (zerop times)
-        (if (eq (length examples) 1)
-            (insert "\n  Example:\n\n")
-          (insert "\n  Examples:\n\n")))
+        (if (> num-examples 1)
+            (insert "\n  Examples:\n\n")
+          ;; Some functions have more than one example per group.
+          ;; Count the number of arrows to know if we need to
+          ;; pluralize "Example".
+          (let* ((text (cdr example))
+                 (count 0)
+                 (pos 0)
+                 (end (length text))
+                 (double-arrow (if (char-displayable-p ?⇒)
+                                   "    ⇒"
+                                 "    =>"))
+                 (double-arrow-example (if (char-displayable-p ?⇒)
+                                           "    e.g. ⇒"
+                                         "    e.g. =>"))
+                 (single-arrow (if (char-displayable-p ?→)
+                                   "    →"
+                                 "    ->")))
+            (while (and (< pos end)
+                        (or (string-match double-arrow text pos)
+                            (string-match double-arrow-example text pos)
+                            (string-match single-arrow text pos)))
+              (setq count (1+ count)
+                    pos (match-end 0)))
+            (if (> count 1)
+                (insert "\n  Examples:\n\n")
+              (insert "\n  Example:\n\n")))))
       (setq times (1+ times))
       (insert "  ")
       (insert (cdr example))

diff --git a/test/lisp/emacs-lisp/shortdoc-tests.el b/test/lisp/emacs-lisp/shortdoc-tests.el
index a65a4a5ddc3b4e2915bfccfe170e736a96bbaa51..d2dfbc6686429a3e33a4274678735fdaa35e0d01 100644 (file)
--- a/test/lisp/emacs-lisp/shortdoc-tests.el
+++ b/test/lisp/emacs-lisp/shortdoc-tests.el
@@ -75,6 +75,21 @@
   (should (equal '((regexp . "(string-match-p \"^[fo]+\" \"foobar\")\n    => 0"))
                  (shortdoc-function-examples 'string-match-p))))
 
+(ert-deftest shortdoc-help-fns-examples-function-test ()
+  "Test that `shortdoc-help-fns-examples-function' correctly prints ELisp function examples."
+  (with-temp-buffer
+    (shortdoc-help-fns-examples-function 'string-fill)
+    (should (equal "\n  Examples:\n\n  (string-fill \"Three short words\" 12)\n    => \"Three short\\nwords\"\n  (string-fill \"Long-word\" 3)\n    => \"Long-word\"\n\n"
+                   (buffer-substring-no-properties (point-min) (point-max))))
+    (erase-buffer)
+    (shortdoc-help-fns-examples-function 'assq)
+    (should (equal "\n  Examples:\n\n  (assq 'foo '((foo . bar) (zot . baz)))\n    => (foo . bar)\n\n  (assq 'b '((a . 1) (b . 2)))\n    => (b . 2)\n\n"
+                   (buffer-substring-no-properties (point-min) (point-max))))
+    (erase-buffer)
+    (shortdoc-help-fns-examples-function 'string-trim)
+    (should (equal "\n  Example:\n\n  (string-trim \" foo \")\n    => \"foo\"\n\n"
+                   (buffer-substring-no-properties (point-min) (point-max))))))
+
 (provide 'shortdoc-tests)
 
 ;;; shortdoc-tests.el ends here