From 9008dfbe3dc7fc338788d544ee2553b8367d13c6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Mart=C3=ADn?= <mardani29@yahoo.es>
Date: Sat, 29 May 2021 13:26:59 +0200
Subject: [PATCH 1/2] Improve the documentation of documentation groups

* doc/lispref/help.texi (Documentation Groups): Fix typos and add an
example.
* lisp/emacs-lisp/shortdoc.el (define-short-documentation-group): Add
:no-eval* and :result-string keywords to the docstring.  (Bug#48730)
---
 doc/lispref/help.texi       | 18 ++++++++++++++----
 lisp/emacs-lisp/shortdoc.el |  2 ++
 2 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 298bec5230..dbbc34fb3a 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -839,7 +839,7 @@ Documentation Groups
 @end example
 
 @noindent
-will be printed as
+will result in:
 
 @example
 (concat "foo" "bar" "zot")
@@ -866,13 +866,14 @@ Documentation Groups
 @end example
 
 @item :no-eval*
-Like @code{:no-eval}, but alaways inserts @samp{[it depends]} as the
-result.
+Like @code{:no-eval}, but always inserts @samp{[it depends]} as the
+result.  For instance:
 
 @example
 :no-eval* (buffer-string)
 @end example
 
+@noindent
 will result in:
 
 @example
@@ -894,12 +895,21 @@ Documentation Groups
 
 @item :eg-result
 Used to output an example result from non-evaluating example forms.
+For instance:
 
 @example
 :no-eval (looking-at "f[0-9]")
 :eg-result t
 @end example
 
+@noindent
+will result in:
+
+@example
+(looking-at "f[0-9]")
+eg. @click{} t
+@end example
+
 @item :result-string
 @itemx :eg-result-string
 These two are the same as @code{:result} and @code{:eg-result},
@@ -951,7 +961,7 @@ Documentation Groups
 
 @defun shortdoc-add-function shortdoc-add-function group section elem
 Lisp packages can add functions to groups with this command.  Each
-@var{elem} should be a function descriptions, as described above.
+@var{elem} should be a function description, as described above.
 @var{group} is the function group, and @var{section} is what section
 in the function group to insert the function into.
 
diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 38d8ad6cc1..c9484dcb68 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -60,8 +60,10 @@ define-short-documentation-group
    :args ARGS
    :eval EXAMPLE-FORM
    :no-eval EXAMPLE-FORM
+   :no-eval* EXAMPLE-FORM
    :no-value EXAMPLE-FORM
    :result RESULT-FORM
+   :result-string RESULT-FORM
    :eg-result RESULT-FORM
    :eg-result-string RESULT-FORM)
 
-- 
2.31.0