CVS update by aidan xemacs/src ...

[xemacs-cvs at xemacs.org]

  User: aidan   
  Date: 07/01/20 17:57:09

  Modified:    xemacs/src ChangeLog eval.c fns.c
Log:
Fill out docstrings fo `function,' `quote' and `require.'

Revision  Changes    Path
1.1039    +9 -0      XEmacs/xemacs/src/ChangeLog

Index: ChangeLog
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/ChangeLog,v
retrieving revision 1.1038
retrieving revision 1.1039
diff -u -p -r1.1038 -r1.1039
--- ChangeLog	2007/01/08 13:33:42	1.1038
+++ ChangeLog	2007/01/20 16:57:05	1.1039
@@ -1,3 +1,12 @@
+2007-01-20  Aidan Kehoe  <kehoea at parhasard.net>
+
+	* 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. 
+
 2007-01-06  Vin Shelton  <acs at xemacs.org>
 
 	* fileio.c (check_writable): Check old-style readonly bit first.



1.94      +19 -2     XEmacs/xemacs/src/eval.c

Index: eval.c
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/eval.c,v
retrieving revision 1.93
retrieving revision 1.94
diff -u -p -r1.93 -r1.94
--- eval.c	2006/08/29 14:10:54	1.93
+++ eval.c	2007/01/20 16:57:06	1.94
@@ -1177,6 +1177,15 @@ The return value of the `setq' form is t
 
 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 @@ Return the argument, without evaluating 
 
 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))
 {



1.65      +7 -0      XEmacs/xemacs/src/fns.c

Index: fns.c
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/fns.c,v
retrieving revision 1.64
retrieving revision 1.65
diff -u -p -r1.64 -r1.65
--- fns.c	2005/10/25 11:16:24	1.64
+++ fns.c	2007/01/20 16:57:06	1.65
@@ -3582,6 +3582,13 @@ is not loaded; so load the file FILENAME
 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))
 {