[AC21.5 21.4?] Minor documentation fixes

APPROVE COMMIT 21.5 Maybe relevant to 21.4? What do you think, Vin? diff --git a/lisp/ChangeLog b/lisp/ChangeLog index d103655..da18c7a 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog ＠＠ -0,0 +1,8 ＠＠ +2007-01-23 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * cus-face.el (custom-theme-reset-faces): Move code after docstring. + +2007-01-22 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * subr.el (lambda): Improve docstring. + diff --git a/src/ChangeLog b/src/ChangeLog index 5a333f7..88522c9 100644 --- a/src/ChangeLog +++ b/src/ChangeLog ＠＠ -0,0 +1,7 ＠＠ +2007-01-22 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * eval.c (quote): + (function): + * fns.c (Frequire): + Improve docstrings. + diff --git a/lisp/cus-face.el b/lisp/cus-face.el index b4a0ecc..a2a9a9c 100644 --- a/lisp/cus-face.el +++ b/lisp/cus-face.el ＠＠ -359,7 +359,6 ＠＠ FACE. Nil otherwise." ;;;###autoload (defun custom-theme-reset-faces (theme &rest args) - (custom-check-theme theme) "Reset the value of the face to values previously defined. Associate this setting with THEME. ＠＠ -368,6 +367,7 ＠＠ ARGS is a list of lists of the form (face to-theme) This means reset face to its value in to-theme." + (custom-check-theme theme) (mapc #'(lambda (arg) (apply #'custom-theme-reset-internal-face arg) (custom-push-theme (car arg) 'theme-face theme 'reset (cadr arg))) diff --git a/lisp/subr.el b/lisp/subr.el index 89061ed..8e00fba 100644 --- a/lisp/subr.el +++ b/lisp/subr.el ＠＠ -79,12 +79,24 ＠＠ function, i.e., stored as the function value of a symbol, passed to funcall or mapcar, etc. ARGS should take the same form as an argument list for a `defun'. -DOCSTRING is an optional documentation string. - If present, it should describe how to call the function. - But documentation strings are usually not useful in nameless functions. -INTERACTIVE should be a call to the function `interactive', which see. -It may also be omitted. -BODY should be a list of lisp expressions." +Optional DOCSTRING is a documentation string. +If present, it should describe how to call the function. Docstrings are +rarely useful unless the lambda will be named, eg, using `fset'. +Optional INTERACTIVE should be a call to the function `interactive'. +BODY should be a list of lisp expressions. + +The byte-compiler treats lambda expressions specially. If the lambda +expression is syntactically a function to be called, it will be compiled +unless protected by `quote'. Conversely, quoting a lambda expression with +`function' hints to the byte-compiler that it should compile the expression. +\(The byte-compiler may or may not actually compile it; for example it will +never compile lambdas nested in a data structure: `'(#'(lambda (x) x))'). + +The byte-compiler will warn about common problems such as the form +`(fset 'f '(lambda (x) x))' (the lambda cannot be byte-compiled; probably +the programmer intended `#'', although leaving the lambda unquoted will +normally suffice), but in general is it the programmer's responsibility to +quote lambda expressions appropriately." `(function (lambda ,＠cdr))) ;; FSF 21.2 has various basic macros here. We don't because they're either diff --git a/src/eval.c b/src/eval.c index fa182c1..500c771 100644 --- a/src/eval.c +++ b/src/eval.c ＠＠ -1178,14 +1178,16 ＠＠ The return value of the `setq' form is the value of the last VAL. 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. +`quote' differs from `function' in that it is a hint that an expression is +data, not a function. In particular, under some circumstances the byte +compiler will compile an expression quoted with `function', but it will +never do so for an expression quoted with `quote'. These issues are most +important for lambda expressions (see `lambda'). + +There is an alternative, more readable, reader syntax for `quote': a Lisp +object preceded by `''. Thus, `'x' is equivalent to `(quote x)', in all +contexts. A print function may use either. Internally the expression is +represented as `(quote x)'). */ (args)) { ＠＠ -1193,17 +1195,20 ＠＠ lambda expressions will be automatically byte-compiled. } DEFUN ("function", Ffunction, 1, UNEVALLED, 0, /* -Like `quote', but preferred for objects which are functions. - -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. +Return the argument, without evaluating it. `(function x)' yields `x'. + +`function' differs from `quote' in that it is a hint that an expression is +a function, not data. In particular, under some circumstances the byte +compiler will compile an expression quoted with `function', but it will +never do so for an expression quoted with `quote'. However, the byte +compiler will not compile an expression buried in a data structure such as +a vector or a list which is not syntactically a function. These issues are +most important for lambda expressions (see `lambda'). + +There is an alternative, more readable, reader syntax for `function': a Lisp +object preceded by `#''. Thus, #'x is equivalent to (function x), in all +contexts. A print function may use either. Internally the expression is +represented as `(function x)'). */ (args)) { diff --git a/src/fns.c b/src/fns.c index 16852e3..bf85bbd 100644 --- a/src/fns.c +++ b/src/fns.c ＠＠ -3576,19 +3576,26 ＠＠ This function updates the value of the variable `features'. } DEFUN ("require", Frequire, 1, 3, 0, /* -If feature FEATURE is not loaded, load it from FILENAME. -If FEATURE is not a member of the list `features', then the feature -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. +Ensure that FEATURE is present in the Lisp environment. +FEATURE is a symbol naming a collection of resources (functions, etc). +Optional FILENAME is a library from which to load resources; it defaults to +the print name of FEATURE. +Optional NOERROR, if non-nil, causes require to return nil rather than signal +`file-error' if loading the library fails. + +If feature FEATURE is present in `features', update `load-history' to reflect +the require and return FEATURE. Otherwise, try to load it from a library. +The normal messages at start and end of loading are suppressed. +If the library is successfully loaded and it calls `(provide FEATURE)', add +FEATURE to `features', update `load-history' and return FEATURE. +If the load succeeds but FEATURE is not provided by the library, signal +`invalid-state'. + +The byte-compiler treats top-level calls to `require' specially, by evaluating +them at compile time (and then compiling them normally). Thus a library may +request that definitions that should be inlined such as macros and defsubsts +be loaded into its compilation environment. Achieving this in other contexts +requires an explicit \(eval-and-compile ...\) block. */ (feature, filename, noerror)) { _______________________________________________ XEmacs-Patches mailing list XEmacs-Patches(a)xemacs.org http://calypso.tux.org/cgi-bin/mailman/listinfo/xemacs-patches