From 12663618dfb5532d6414f6d12706f3ad441c0a15 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 12 Mar 2016 10:26:21 +0200 Subject: [PATCH] Fix documentation of seq.el functions * doc/lispref/sequences.texi (Sequence Functions): Fix typos. Add cross-references. Fix formatting. (Bug#22992) --- doc/lispref/sequences.texi | 60 ++++++++++++++++++++------------------ 1 file 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 -- 2.39.2