Fix documentation of seq.el functions

* doc/lispref/sequences.texi (Sequence Functions): Fix typos.  Add
cross-references.  Fix formatting.  (Bug#22992)

1 files changed, 32 insertions, 28 deletions

diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 9869fe4c510..a54ab104ab5 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -435,23 +435,27 @@ a predicate, this should be a function of one argument.
 
   The @file{seq.el} library can be extended to work with additional
 types of sequential data-structures.  For that purpose, all functions
-are defined using @code{cl-defgeneric}.
+are defined using @code{cl-defgeneric}.  @xref{Generic Functions}, for
+more details about using @code{cl-defgeneric} for adding extensions.
 
 @defun seq-elt sequence index
-  This function the element at the index @var{index} in
-@var{sequence}.  @var{index} can be an integer from zero up to the
-length of @var{sequence} minus one.  For out-of-range values on
-built-in sequence types, @code{seq-elt} behaves like @code{elt}.
-@xref{Definition of elt}.
+  This function returns the element of @var{sequence} at the specified
+@var{index}, which is an integer whose valid value range is zero to
+one less than the length of @var{sequence}.  For out-of-range values
+on built-in sequence types, @code{seq-elt} behaves like @code{elt}.
+For the details, see @ref{Definition of elt}.
 
 @example
 @group
 (seq-elt [1 2 3 4] 2)
 @result{} 3
 @end group
+@end example
 
-  @code{seq-elt} returns settable places using @code{setf}.
+  @code{seq-elt} returns places settable using @code{setf}
+(@pxref{Setting Generalized Variables}).
 
+@example
 @group
 (setq vec [1 2 3 4])
 (setf (seq-elt vec 2) 5)
@@ -552,7 +556,7 @@ starting from the first one for which @var{predicate} returns @code{nil}.
 
 @defun seq-do function sequence
   This function applies @var{function} to each element of
-@var{sequence} in turn (presumably for side effects) and returns
+@var{sequence} in turn (presumably for side effects), and returns
 @var{sequence}.
 @end defun
 
@@ -574,9 +578,10 @@ element of @var{sequence}.  The returned value is a list.
 
 @defun seq-mapn function &rest sequences
   This function returns the result of applying @var{function} to each
-element of @var{sequences}.  The arity of @var{function} must match
-the number of sequences.  Mapping stops at the shortest sequence, and
-the returned value is a list.
+element of @var{sequences}.  The arity (@pxref{What Is a Function,
+sub-arity}) of @var{function} must match the number of sequences.
+Mapping stops at the end of the shortest sequence, and the returned
+value is a list.
 
 @example
 @group
@@ -675,13 +680,13 @@ applying @var{predicate} to each element of @var{sequence} in turn.
 @end defun
 
 @defun seq-find predicate sequence &optional default
-  This function returns the first element for which @var{predicate}
-returns non-@code{nil} in @var{sequence}.  If no element matches
-@var{predicate}, @var{default} is returned.
+  This function returns the first element in @var{sequence} for which
+@var{predicate} returns non-@code{nil}.  If no element matches
+@var{predicate}, the function returns @var{default}.
 
 Note that this function has an ambiguity if the found element is
-identical to @var{default}, as it cannot be known if an element was
-found or not.
+identical to @var{default}, as in that case it cannot be known whether
+an element was found or not.
 
 @example
 @group
@@ -854,7 +859,7 @@ list if @var{type} is @code{nil}.
   This function returns a list of the elements of @var{sequence}
 grouped into sub-sequences of length @var{n}.  The last sequence may
 contain less elements than @var{n}.  @var{n} must be an integer.  If
-@var{n} is a negative integer or 0, nil is returned.
+@var{n} is a negative integer or 0, the return value is @code{nil}.
 
 @example
 @group
@@ -932,9 +937,9 @@ of type @var{type}.  @var{type} can be one of the following symbols:
 @end defun
 
 @defun seq-min sequence
-  This function returns the smallest element of
-@var{sequence}. @var{sequence} must be a sequence of numbers or
-markers.
+  This function returns the smallest element of @var{sequence}.  The
+elements of @var{sequence} must be numbers or markers
+(@pxref{Markers}).
 
 @example
 @group
@@ -949,9 +954,8 @@ markers.
 @end defun
 
 @defun seq-max sequence
-  This function returns the largest element of
-@var{sequence}. @var{sequence} must be a sequence of numbers or
-markers.
+  This function returns the largest element of @var{sequence}.  The
+elements of @var{sequence} must be numbers or markers.
 
 @example
 @group
@@ -967,16 +971,16 @@ markers.
 
 @defmac seq-doseq (var sequence) body@dots{}
 @cindex sequence iteration
-  This macro is like @code{dolist}, except that @var{sequence} can be a list,
-vector or string (@pxref{Iteration} for more information about the
-@code{dolist} macro).  This is primarily useful for side-effects.
+  This macro is like @code{dolist} (@pxref{Iteration, dolist}), except
+that @var{sequence} can be a list, vector or string.  This is
+primarily useful for side-effects.
 @end defmac
 
 @defmac seq-let arguments sequence body@dots{}
 @cindex sequence destructuring
   This macro binds the variables defined in @var{arguments} to the
-elements of the sequence @var{sequence}.  @var{arguments} can itself
-include sequences allowing for nested destructuring.
+elements of @var{sequence}.  @var{arguments} can themselves include
+sequences, allowing for nested destructuring.
 
 The @var{arguments} sequence can also include the @code{&rest} marker
 followed by a variable name to be bound to the rest of