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.