* doc strings of reverse and nreverse.
@ 2003-11-20 4:10 Luc Teirlinck
2003-11-20 4:29 ` Luc Teirlinck
2003-11-20 10:42 ` Kim F. Storm
0 siblings, 2 replies; 4+ messages in thread
From: Luc Teirlinck @ 2003-11-20 4:10 UTC (permalink / raw)
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.
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: doc strings of reverse and nreverse.
2003-11-20 4:10 doc strings of reverse and nreverse Luc Teirlinck
@ 2003-11-20 4:29 ` Luc Teirlinck
2003-11-20 10:42 ` Kim F. Storm
1 sibling, 0 replies; 4+ messages in thread
From: Luc Teirlinck @ 2003-11-20 4:29 UTC (permalink / raw)
Cc: emacs-devel
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
============================================================
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: doc strings of reverse and nreverse.
2003-11-20 4:10 doc strings of reverse and nreverse Luc Teirlinck
2003-11-20 4:29 ` Luc Teirlinck
@ 2003-11-20 10:42 ` Kim F. Storm
2003-11-21 5:12 ` Luc Teirlinck
1 sibling, 1 reply; 4+ messages in thread
From: Kim F. Storm @ 2003-11-20 10:42 UTC (permalink / raw)
Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: doc strings of reverse and nreverse.
2003-11-20 10:42 ` Kim F. Storm
@ 2003-11-21 5:12 ` Luc Teirlinck
0 siblings, 0 replies; 4+ messages in thread
From: Luc Teirlinck @ 2003-11-21 5:12 UTC (permalink / raw)
Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2003-11-21 5:12 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2003-11-20 4:10 doc strings of reverse and nreverse Luc Teirlinck
2003-11-20 4:29 ` Luc Teirlinck
2003-11-20 10:42 ` Kim F. Storm
2003-11-21 5:12 ` Luc Teirlinck
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).