Re: [Emacs-diffs] trunk r117133: * doc/lispref/sequences.texi (Sequence Functions): Update nreverse.

Re: [Emacs-diffs] trunk r117133: * doc/lispref/sequences.texi (Sequence Functions): Update nreverse.

[Stefan Monnier]

>    This function reverses the order of the elements of @var{seq}.
> -If @var{seq} is a list, @code{nreverse} alters its by reversing the @sc{cdr}s
> +If @var{seq} is a list, @code{nreverse} alters it by reversing the @sc{cdr}s
>  in the cons cells.  The cons cell that used to be the last one in @var{seq}
>  becomes the first cons cell of the value.  If @var{seq} is a vector or
> -bool vector, its items are placed in the same vector in a reversed order.
> +bool vector, its items are placed in the same vector in a reversed
> +order.  If @var{seq} is a string, it works like @code{reverse} i.e., no
> +destructive modifcation in preference to treat strings as immutable.
 
The docstring is good, but the above manual entry is too specific.
We don't want to specify when side-effects are used and when not.


        Stefan

Re: [Emacs-diffs] trunk r117133: * doc/lispref/sequences.texi (Sequence Functions): Update nreverse.

[Leo Liu]

On 2014-05-21 08:38 -0400, Stefan Monnier wrote:
> The docstring is good, but the above manual entry is too specific.
> We don't want to specify when side-effects are used and when not.

Do you mean simplify the doc to something like this:

=== modified file 'doc/lispref/sequences.texi'
--- doc/lispref/sequences.texi	2014-05-21 03:49:58 +0000
+++ doc/lispref/sequences.texi	2014-05-22 00:21:12 +0000
@@ -265,12 +265,7 @@
 @cindex reversing a list
 @cindex reversing a vector
   This function reverses the order of the elements of @var{seq}.
-If @var{seq} is a list, @code{nreverse} alters it by reversing the @sc{cdr}s
-in the cons cells.  The cons cell that used to be the last one in @var{seq}
-becomes the first cons cell of the value.  If @var{seq} is a vector or
-bool vector, its items are placed in the same vector in a reversed
-order.  If @var{seq} is a string, it works like @code{reverse} i.e., no
-destructive modifcation in preference to treat strings as immutable.
+The original @var{seq} may be modified.
 
   For example:

Re: [Emacs-diffs] trunk r117133: * doc/lispref/sequences.texi (Sequence Functions): Update nreverse.

[Stefan Monnier]

>> The docstring is good, but the above manual entry is too specific.
>> We don't want to specify when side-effects are used and when not.
> Do you mean simplify the doc to something like this:

Pretty much, yes, tho it should insist on the fact that this is the
difference between it and `reverse'.


        Stefan