docstring of `kill-buffer'

[Juanma Barranquero]

I have a few problems with the current docstring of `kill-buffer':

 - It says that it returns t if the buffer is killed, and "nil if
user says no". It would be more accurate to simply say "nil if it is
not killed"; it's not always the user who stops the killing (for
example, I use Noah S. Friedman's protbuf.el).

- It does not mention `kill-buffer-query-functions', which is yet
more puzzling after the previous paragraph.

- The description of `kill-buffer-hook' is too verbose, and insists
on saying that it "may be local to that buffer"; but
`kill-buffer-hook' is not different from any other normal hook.

I propose the following change, which also clarifies a bit
`kill-buffer-query-functions'.

                   /L/e/k/t/u


Index: src/buffer.c
===================================================================
RCS file: /cvsroot/emacs/emacs/src/buffer.c,v
retrieving revision 1.516
diff -u -2 -r1.516 buffer.c
--- src/buffer.c        11 Dec 2006 15:41:07 -0000      1.516
+++ src/buffer.c        11 Dec 2006 17:04:22 -0000
@@ -1332,13 +1332,14 @@
 DEFUN ("kill-buffer", Fkill_buffer, Skill_buffer, 1, 1, "bKill buffer: ",
       doc: /* Kill the buffer BUFFER.
-The argument may be a buffer or may be the name of a buffer.
-An argument of nil means kill the current buffer.
+The argument may be a buffer or the name of a buffer.
+With a nil argument, kill the current buffer.

-Value is t if the buffer is actually killed, nil if user says no.
+Value is t if the buffer is actually killed, nil otherwise.

-The value of `kill-buffer-hook' (which may be local to that buffer),
-if not void, is a list of functions to be called, with no arguments,
-before the buffer is actually killed.  The buffer to be killed is current
-when the hook functions are called.
+The functions in `kill-buffer-query-functions' are called with BUFFER as
+the current buffer.  If any of them returns nil, the buffer is not killed.
+
+The hook `kill-buffer-hook' is run before the buffer is actually killed.
+The buffer being killed will be current while the hook is running.

Any processes that have this buffer as the `process-buffer' are killed
@@ -6045,5 +6046,7 @@

  DEFVAR_LISP ("kill-buffer-query-functions", &Vkill_buffer_query_functions,
-              doc: /* List of functions called with no args to query before
killing a buffer.  */);
+              doc: /* List of functions called with no args to query before
killing a buffer.
+The buffer being killed will be current while the functions are running.
+If any of them returns nil, the buffer is not killed.  */);
  Vkill_buffer_query_functions = Qnil;