[Emacs-diffs] /srv/bzr/emacs/emacs-24 r108147: Doc fixes

[Glenn Morris]

------------------------------------------------------------
revno: 108147
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Mon 2012-09-24 00:12:35 -0700
message:
  Doc fixes
  
  * src/eval.c (Frun_hook_with_args, Frun_hook_with_args_until_success)
  (Frun_hook_with_args_until_failure): Doc fixes.
modified:
  src/ChangeLog
  src/eval.c

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2012-09-21 03:55:23 +0000
+++ b/src/ChangeLog     2012-09-24 07:12:35 +0000
@@ -1,3 +1,8 @@
+2012-09-24  Glenn Morris  <address@hidden>
+
+       * eval.c (Frun_hook_with_args, Frun_hook_with_args_until_success)
+       (Frun_hook_with_args_until_failure): Doc fixes.
+
 2012-09-21  Chong Yidong  <address@hidden>
 
        * image.c (define_image_type): Avoid adding duplicate types to

=== modified file 'src/eval.c'
--- a/src/eval.c        2012-09-18 01:07:13 +0000
+++ b/src/eval.c        2012-09-24 07:12:35 +0000
@@ -2551,14 +2551,10 @@
 DEFUN ("run-hook-with-args", Frun_hook_with_args,
        Srun_hook_with_args, 1, MANY, 0,
        doc: /* Run HOOK with the specified arguments ARGS.
-HOOK should be a symbol, a hook variable.  If HOOK has a non-nil
-value, that value may be a function or a list of functions to be
-called to run the hook.  If the value is a function, it is called with
-the given arguments and its return value is returned.  If it is a list
-of functions, those functions are called, in order,
-with the given arguments ARGS.
-It is best not to depend on the value returned by `run-hook-with-args',
-as that may change.
+HOOK should be a symbol, a hook variable.  The value of HOOK
+may be nil, a function, or a list of functions.  Call each
+function in order with arguments ARGS.  The final return value
+is unspecified.
 
 Do not use `make-local-variable' to make a hook variable buffer-local.
 Instead, use `add-hook' and specify t for the LOCAL argument.
@@ -2568,18 +2564,18 @@
   return run_hook_with_args (nargs, args, funcall_nil);
 }
 
+/* NB this one still documents a specific non-nil return value.
+   (As did run-hook-with-args and run-hook-with-args-until-failure
+   until they were changed in 24.1.)  */
 DEFUN ("run-hook-with-args-until-success", Frun_hook_with_args_until_success,
        Srun_hook_with_args_until_success, 1, MANY, 0,
        doc: /* Run HOOK with the specified arguments ARGS.
-HOOK should be a symbol, a hook variable.  If HOOK has a non-nil
-value, that value may be a function or a list of functions to be
-called to run the hook.  If the value is a function, it is called with
-the given arguments and its return value is returned.
-If it is a list of functions, those functions are called, in order,
-with the given arguments ARGS, until one of them
-returns a non-nil value.  Then we return that value.
-However, if they all return nil, we return nil.
-If the value of HOOK is nil, this function returns nil.
+HOOK should be a symbol, a hook variable.  The value of HOOK
+may be nil, a function, or a list of functions.  Call each
+function in order with arguments ARGS, stopping at the first
+one that returns non-nil, and return that value.  Otherwise (if
+all functions return nil, or if there are no functions to call),
+return nil.
 
 Do not use `make-local-variable' to make a hook variable buffer-local.
 Instead, use `add-hook' and specify t for the LOCAL argument.
@@ -2598,15 +2594,12 @@
 DEFUN ("run-hook-with-args-until-failure", Frun_hook_with_args_until_failure,
        Srun_hook_with_args_until_failure, 1, MANY, 0,
        doc: /* Run HOOK with the specified arguments ARGS.
-HOOK should be a symbol, a hook variable.  If HOOK has a non-nil
-value, that value may be a function or a list of functions to be
-called to run the hook.  If the value is a function, it is called with
-the given arguments.  Then we return nil if the function returns nil,
-and t if it returns non-nil.
-If it is a list of functions, those functions are called, in order,
-with the given arguments ARGS, until one of them returns nil.
-Then we return nil.  However, if they all return non-nil, we return t.
-If the value of HOOK is nil, this function returns t.
+HOOK should be a symbol, a hook variable.  The value of HOOK
+may be nil, a function, or a list of functions.  Call each
+function in order with arguments ARGS, stopping at the first
+one that returns nil, and return nil.  Otherwise (if all functions
+return non-nil, or if there are no functions to call), return non-nil
+\(do not rely on the precise return value in this case).
 
 Do not use `make-local-variable' to make a hook variable buffer-local.
 Instead, use `add-hook' and specify t for the LOCAL argument.