From d393cefbbf8f60bf62b94fa775daa8b69e108f49 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Mon, 24 Sep 2012 00:12:35 -0700 Subject: [PATCH] Doc fixes * src/eval.c (Frun_hook_with_args, Frun_hook_with_args_until_success) (Frun_hook_with_args_until_failure): Doc fixes. --- src/ChangeLog | 5 +++++ src/eval.c | 45 +++++++++++++++++++-------------------------- 2 files changed, 24 insertions(+), 26 deletions(-) diff --git a/src/ChangeLog b/src/ChangeLog index 15b47934424..96546df6638 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,8 @@ +2012-09-24 Glenn Morris + + * 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 * image.c (define_image_type): Avoid adding duplicate types to diff --git a/src/eval.c b/src/eval.c index 332c3326fce..f6056e33c28 100644 --- a/src/eval.c +++ b/src/eval.c @@ -2551,14 +2551,10 @@ usage: (run-hooks &rest HOOKS) */) 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 @@ usage: (run-hook-with-args HOOK &rest ARGS) */) 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 @@ funcall_not (ptrdiff_t nargs, Lisp_Object *args) 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. -- 2.39.2