master 4b84095: Improve documentation of shortdoc features

[Eli Zaretskii]

branch: master
commit 4b84095d2373eb0b26308d6c622ce9ab89a0efa5
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    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.
---
 doc/lispref/help.texi       | 105 ++++++++++++++++++++++++--------------------
 lisp/emacs-lisp/shortdoc.el |  13 +++---
 lisp/help-fns.el            |   4 +-
 3 files changed, 67 insertions(+), 55 deletions(-)

diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index f513a70..2fa54e3 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.
 
diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 1843db8..eaa4ece 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -67,13 +67,13 @@ FUNCTIONS is a list of elements on the form:
 BOOL should be non-nil if the function isn't documented in the
 manual.
 
-ARGS is optional, and the functions definition is displayed
-instead in not present.
+ARGS is optional; the function's signature is displayed if ARGS
+is not present.
 
 If EVAL isn't a string, it will be printed with `prin1', and then
-evaled to give a result, which is also printed.  If it's a
+evaluated to give a result, which is also printed.  If it's a
 string, it'll be inserted as is, then the string will be `read',
-and then evaled.
+and then evaluated.
 
 There can be any number of :example/:result elements."
   `(progn
@@ -957,8 +957,8 @@ There can be any number of :example/:result elements."
 
 ;;;###autoload
 (defun shortdoc-display-group (group)
-  "Pop to a buffer and display short documentation for functions in GROUP."
-  (interactive (list (completing-read "Show functions in: "
+  "Pop to a buffer with short documentation summary for functions in GROUP."
+  (interactive (list (completing-read "Show summary for functions in: "
                                       (mapcar #'car shortdoc--groups))))
   (when (stringp group)
     (setq group (intern group)))
@@ -1079,6 +1079,7 @@ There can be any number of :example/:result elements."
 
 (defun shortdoc-add-function (group section elem)
   "Add ELEM to shortdoc GROUP in SECTION.
+If GROUP doesn't exist, it will be created.
 If SECTION doesn't exist, it will be added.
 
 Example:
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index ee626eb..07b4c40 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -40,8 +40,8 @@
 (defvar help-fns-describe-function-functions nil
   "List of functions to run in help buffer in `describe-function'.
 Those functions will be run after the header line and argument
-list was inserted, and before the documentation will be inserted.
-The functions will receive the function name as argument.
+list was inserted, and before the documentation is be inserted.
+The functions will be called with one argument: the function's symbol.
 They can assume that a newline was output just before they were called,
 and they should terminate any of their own output with a newline.
 By convention they should indent their output by 2 spaces.")