Add functions to query Emacs Lisp examples registered in shortdoc

* lisp/emacs-lisp/shortdoc.el (shortdoc--display-function): Add
a new shortdoc-example text property so that ELisp examples can
be searched for later.
(shortdoc--insert-group-in-buffer): New function extracted from
the buffer insertion code in 'shortdoc-display-group'.
(shortdoc-display-group): Implement in terms of
'shortdoc--insert-group-in-buffer'.
(shortdoc-function-examples): New function that returns an alist
of Emacs Lisp examples from shortdoc.
(shortdoc-help-fns-examples-function): New function to insert
Emacs Lisp function examples in *Help* buffers, if added to
'help-fns-describe-function-functions'.
*
test/lisp/emacs-lisp/shortdoc-tests.el (shortdoc-function-examples-test):
Test it.
* doc/emacs/help.texi (Name Help): Document in the user manual.
* doc/lispref/help.texi (Documentation Groups): Document it.
* etc/NEWS: Advertise it. (Bug#61877)

1 files changed, 10 insertions, 0 deletions

diff --git a/test/lisp/emacs-lisp/shortdoc-tests.el b/test/lisp/emacs-lisp/shortdoc-tests.el
index 516d095767f..a65a4a5ddc3 100644
--- a/test/lisp/emacs-lisp/shortdoc-tests.el
+++ b/test/lisp/emacs-lisp/shortdoc-tests.el
@@ -65,6 +65,16 @@
         (when buf
           (kill-buffer buf))))))
 
+(ert-deftest shortdoc-function-examples-test ()
+  "Test the extraction of usage examples of some Elisp functions."
+  (should (equal '((list . "(delete 2 (list 1 2 3 4))\n    => (1 3 4)\n  (delete \"a\" (list \"a\" \"b\" \"c\" \"d\"))\n    => (\"b\" \"c\" \"d\")"))
+                 (shortdoc-function-examples 'delete)))
+  (should (equal '((alist . "(assq 'foo '((foo . bar) (zot . baz)))\n    => (foo . bar)")
+                   (list . "(assq 'b '((a . 1) (b . 2)))\n    => (b . 2)"))
+                 (shortdoc-function-examples 'assq)))
+  (should (equal '((regexp . "(string-match-p \"^[fo]+\" \"foobar\")\n    => 0"))
+                 (shortdoc-function-examples 'string-match-p))))
+
 (provide 'shortdoc-tests)
 
 ;;; shortdoc-tests.el ends here