doc strings of reverse and nreverse.

doc strings of reverse and nreverse.

[Luc Teirlinck]

The doc strings of `reverse' and `nreverse' are strange and cryptic.

Do C-h f reverse RET

Result:

reverse is a built-in function.
(reverse LIST)

Reverse LIST, copying.  Returns the beginning of the reversed list.
See also the function `nreverse', which is used more often.

My comments:

The "beginning" of the reversed list?  How much of the beginning?
Whenever I tried `reverse' it always returned the entire reversed
list, like the Common Lisp function of the same name.  Does it _ever_
do anything else?  If yes, when and what is the "else"?  If not, what
does that strange sentence mean?  If it ever does anything else, then
there still is a bug in the new version of number-sequence I
submitted, but there would be bugs all over Emacs.

Same questions for `nreverse':

reverse is a built-in function.
(nreverse LIST)

Reverse LIST by modifying cdr pointers.
Returns the beginning of the reversed list.

Sincerely,

Luc.

Re: doc strings of reverse and nreverse.

[Luc Teirlinck]

I took a look at the C code of Freverse and Fnreverse and they do
indeed always return the entire reversed list (except when they throw
an error, of course).  So why those confusing doc strings?  The
following would get rid of them.  I could commit if desired.


===File ~/fns-diff==========================================
cd ~/emacscvsdir/emacs/src/
diff -c /home/teirllm/fns.old.c /home/teirllm/emacscvsdir/emacs/src/fns.c
*** /home/teirllm/fns.old.c	Mon Nov 17 21:24:17 2003
--- /home/teirllm/emacscvsdir/emacs/src/fns.c	Wed Nov 19 22:22:57 2003
***************
*** 1840,1846 ****
  
  DEFUN ("nreverse", Fnreverse, Snreverse, 1, 1, 0,
         doc: /* Reverse LIST by modifying cdr pointers.
! Returns the beginning of the reversed list.  */)
       (list)
       Lisp_Object list;
  {
--- 1840,1846 ----
  
  DEFUN ("nreverse", Fnreverse, Snreverse, 1, 1, 0,
         doc: /* Reverse LIST by modifying cdr pointers.
! Return the reversed list.  */)
       (list)
       Lisp_Object list;
  {
***************
*** 1863,1869 ****
  }
  
  DEFUN ("reverse", Freverse, Sreverse, 1, 1, 0,
!        doc: /* Reverse LIST, copying.  Returns the beginning of the reversed list.
  See also the function `nreverse', which is used more often.  */)
       (list)
       Lisp_Object list;
--- 1863,1869 ----
  }
  
  DEFUN ("reverse", Freverse, Sreverse, 1, 1, 0,
!        doc: /* Reverse LIST, copying.  Return the reversed list.
  See also the function `nreverse', which is used more often.  */)
       (list)
       Lisp_Object list;

Diff finished at Wed Nov 19 22:23:49
============================================================

Re: doc strings of reverse and nreverse.

[Kim F. Storm]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> The doc strings of `reverse' and `nreverse' are strange and cryptic.
> 
> Do C-h f reverse RET
> 
> Result:
> 
> reverse is a built-in function.
> (reverse LIST)
> 
> Reverse LIST, copying.  Returns the beginning of the reversed list.
> See also the function `nreverse', which is used more often.
> 
> My comments:
> 
> The "beginning" of the reversed list?  How much of the beginning?

It's "beginning of list" in the meaning "pointer to first element in
the list".

Which in our book is just "the list".

I agree that "beginning of" should be removed from doc strings.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: doc strings of reverse and nreverse.

[Luc Teirlinck]

Kim Storm wrote:

   It's "beginning of list" in the meaning "pointer to first element in
   the list".

I should have thought of that.  However, this is the C way of thinking
about things and I am not used to see Lisp documentation strings
written in C style terminology.  That is what confused me.

   I agree that "beginning of" should be removed from doc strings.

If will wait a little while, to make sure that there are no objections.
If there are none, I will commit my changes to the doc strings.

Sincerely,

Luc.