[COMMIT] Fill out docstrings fo `function,' `quote' and `require.'

APPROVE COMMIT NOTE: This patch has been committed. src/ChangeLog addition: 2007-01-20 Aidan Kehoe <kehoea(a)parhasard.net&gt; * eval.c: Document in more detail what happens with byte-compilation, `function', and `quote'. * fns.c: Mention that `require' is evaluated both at byte-compile time and at runtime. XEmacs Trunk source patch: Diff command: cvs -q diff -Nu Files affected: src/fns.c =================================================================== RCS src/eval.c =================================================================== RCS Index: src/eval.c =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/src/eval.c,v retrieving revision 1.93 diff -u -u -r1.93 eval.c --- src/eval.c 2006/08/29 14:10:54 1.93 +++ src/eval.c 2007/01/20 16:51:06 ＠＠ -1177,6 +1177,15 ＠＠ DEFUN ("quote", Fquote, 1, UNEVALLED, 0, /* Return the argument, without evaluating it. `(quote x)' yields `x'. + +There is an alternative and more used reader syntax for `quote'. Precede +any Lisp object with a single apostrophe, and that Lisp object will be +returned unevaluated. 'x is thus equivalent to (quote x). + +Do not use `quote' or the single apostrophe for lambda expressions that you +would prefer to be byte-compiled. Use `function', which see, or take +advantage of the fact that lambda expressions are self-quoting and such +lambda expressions will be automatically byte-compiled. */ (args)) { ＠＠ -1185,8 +1194,16 ＠＠ DEFUN ("function", Ffunction, 1, UNEVALLED, 0, /* Like `quote', but preferred for objects which are functions. -In byte compilation, `function' causes its argument to be compiled. -`quote' cannot do that. + +As with `quote' there is an alternative reader syntax for `function' which +in practice is used more often. Writing #'OBJECT is equivalent to writing +\(function OBJECT), where OBJECT is some Lisp object. + +In byte compilation, `function' causes a lambda expression argument to be +compiled. `quote' cannot do that. lambda expressions are, however, +self-quoting, and self-quoted lambda expressions will be byte-compiled. +Only lambda expressions explicitly quoted with `quote' or that occur in +nested data lists will not be byte-compiled. */ (args)) { Index: src/fns.c =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/src/fns.c,v retrieving revision 1.64 diff -u -u -r1.64 fns.c --- src/fns.c 2005/10/25 11:16:24 1.64 +++ src/fns.c 2007/01/20 16:51:08 ＠＠ -3582,6 +3582,13 ＠＠ If FILENAME is omitted, the printname of FEATURE is used as the file name. If optional third argument NOERROR is non-nil, then return nil if the file is not found instead of signaling an error. +Normally the return value is FEATURE. +The normal messages at start and end of loading FILENAME are suppressed. + +In order to make it possible for a required package to provide macros to be +expanded at byte-compilation time, top level calls of `require' are +evaluated both at byte-compile time and at run time. That is, any top-level +call to `require' is wrapped in an implicit \(eval-and-compile ...\) block. */ (feature, filename, noerror)) { -- When I was in the scouts, the leader told me to pitch a tent. I couldn't find any pitch, so I used creosote. _______________________________________________ XEmacs-Patches mailing list XEmacs-Patches(a)xemacs.org http://calypso.tux.org/cgi-bin/mailman/listinfo/xemacs-patches