* 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).