Improve documentation of shortdoc features

* lisp/help-fns.el (help-fns-describe-function-functions): Doc
fix.
* lisp/emacs-lisp/shortdoc.el (define-short-documentation-group)
(shortdoc-display-group, shortdoc-add-function): Doc fixes.

* doc/lispref/help.texi (Documentation Groups): Improve the
recently-added documentation and the indexing.

1 files changed, 58 insertions, 47 deletions

diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index f513a709491..2fa54e3b66b 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -800,76 +800,64 @@ if the user types the help character again.
 @node Documentation Groups
 @section Documentation Groups
 @cindex documentation groups
+@cindex groups of functions
+@cindex function groups
 
 Emacs can list functions based on various groupings.  For instance,
 @code{string-trim} and @code{mapconcat} are ``string'' functions, so
 @kbd{M-x shortdoc-display-group RET string RET} will give an overview
-of functions that do things with strings.
+of functions that operate on strings.
 
 The documentation groups are created with the
-@code{define-short-documentation-group} macro.  Here's a very short
-example:
+@code{define-short-documentation-group} macro.
+
+@defmac define-short-documentation-group group &rest functions
+Define @var{group} as a group of functions, and provide short
+summaries of using those functions.  The optional argument
+@var{functions} is a list whose elements are of the form:
 
 @lisp
-(define-short-documentation-group string
-  "Creating Strings"
-  (substring
-   :eval (substring "foobar" 0 3)
-   :eval (substring "foobar" 3))
-  (concat
-   :eval (concat "foo" "bar" "zot")))
+(@var{func} @var{keyword} @var{val} @dots{})
 @end lisp
 
-The first argument is the name of the group to be defined, and then
-follows any number of function descriptions.
-
-A function can belong to any number of documentation groups.
-
-In addition to function descriptions, the list can also have string
-elements, which are used to divide a documentation group into
-sections.
-
-In each function description, the first element is the name of the
-function, and then the rest of the description is a plist, where the
-first element in each pair is a type, and the second element is a
-value.
-
-The following types are allowed:
+The following keywords are recognized:
 
 @table @code
+
 @item :eval
-The value should be a form that can be evaluated with no side
-effects.  The form will be used in the documentation as printed with
-@code{prin1}, except if it's a string: Then it will be inserted as is,
-and the string with then be @code{read} to return the form.  In any
-case, the form will then be evaluated, and the result used.  For
-instance:
+The value should be a form that has no side effect when evaluated.
+The form will be used in the documentation by printing it with
+@code{prin1} (@pxref{Output Functions}).  However, if the form is a
+string, it will be inserted as-is, and the string will then be
+@code{read} to yield the form.  In any case, the form will then be
+evaluated, and the result used.  For instance:
 
 @example
 :eval (concat "foo" "bar" "zot")
 :eval "(make-string 5 ?x)"
 @end example
 
+@noindent
 will be printed as
 
 @example
 (concat "foo" "bar" "zot")
-=> "foobarzot"
+@result{} "foobarzot"
 (make-string 5 ?x)
-=> "xxxxx"
+@result{} "xxxxx"
 @end example
 
-The reason for allowing both Lisp forms and strings here is so that
-printing can be controlled in the few cases where a certain
+(The reason for allowing both Lisp forms and strings here is so that
+printing could be controlled in the few cases where a certain
 presentation of the form is wished for.  In the example, @samp{?x}
 would otherwise have been printed as @samp{120} if it hadn't been
-included in a string.
+included in a string.)
 
 @item :no-eval
 
-This is like @code{eval}, except that the form will not be evaluated.
-In these cases, a @code{:result} element of some kind should be
-included.
+This is like @code{:eval}, except that the form will not be evaluated.
+In these cases, a @code{:result} element of some kind (see below)
+should be included.
 
 @example
 :no-eval (file-symlink-p "/tmp/foo")
@@ -877,8 +865,8 @@ included.
 @end example
 
 @item :no-eval*
-Like @code{:no-eval}, but a result of @samp{[it depends]} will always
-be inserted.
+Like @code{:no-eval}, but alaways inserts @samp{[it depends]} as the
+result.
 
 @example
 :no-eval* (buffer-string)
@@ -888,12 +876,12 @@ will result in:
 
 @example
 (buffer-string)
--> [it depends]
+@click{} [it depends]
 @end example
 
 @item :no-value
 Like @code{:no-eval}, but is used when the function in question has no
-well-defined return value, but is used for side effect only.
+well-defined return value, and is used for side effect only.
 
 @item :result
 Used to output the result from non-evaluating example forms.
@@ -925,11 +913,11 @@ is unreadable or should be on a particular form:
 @end example
 
 @item :no-manual
-This function is not documented in the manual.
+Indicates that this function is not documented in the manual.
 
 @item :args
 By default, the function's actual argument list is shown.  If
-@code{:args} is present, use that instead.
+@code{:args} is present, they are used instead.
 
 @example
 :args (regexp string)
@@ -937,9 +925,32 @@ By default, the function's actual argument list is shown.  If
 
 @end table
 
+Here's a very short example:
+
+@lisp
+(define-short-documentation-group string
+  "Creating Strings"
+  (substring
+   :eval (substring "foobar" 0 3)
+   :eval (substring "foobar" 3))
+  (concat
+   :eval (concat "foo" "bar" "zot")))
+@end lisp
+
+The first argument is the name of the group to be defined, and then
+follows any number of function descriptions.
+
+@end defmac
+
+A function can belong to any number of documentation groups.
+
+In addition to function descriptions, the list can also have string
+elements, which are used to divide a documentation group into
+sections.
+
 @defun shortdoc-add-function shortdoc-add-function group section elem
-External packages can add functions to groups with this command.  Each
-@var{elem} should be a function descriptions, as seen above.
+Lisp packages can add functions to groups with this command.  Each
+@var{elem} should be a function descriptions, as described above.
 @var{group} is the function group, and @var{section} is what section
 in the function group to insert the function into.