1 files changed, 20 insertions, 17 deletions

diff --git a/src/buffer.c b/src/buffer.c
index e9c3c47a959..6e3b39ad2bb 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -1332,15 +1332,16 @@ See `kill-buffer'."
  */
 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
 with SIGHUP.  */)
@@ -5371,8 +5372,8 @@ This is the same as (default-value 'fill-column).  */);
 This is the same as (default-value 'left-margin).  */);
 
   DEFVAR_LISP_NOPRO ("default-tab-width",
-              &buffer_defaults.tab_width,
-    doc: /* Default value of `tab-width' for buffers that do not override it.
+                     &buffer_defaults.tab_width,
+                     doc: /* Default value of `tab-width' for buffers that do not override it.
 This is the same as (default-value 'tab-width).  */);
 
   DEFVAR_LISP_NOPRO ("default-case-fold-search",
@@ -5694,9 +5695,9 @@ primitives `aref' and `aset' can be used to access elements of a char-table.
 Each of the char-table elements control how to display the corresponding
 text character: the element at index C in the table says how to display
 the character whose code is C.  Each element should be a vector of
-characters or nil.  nil means display the character in the default fashion;
-otherwise, the characters from the vector are delivered to the screen
-instead of the original character.
+characters or nil.  The value nil means display the character in the
+default fashion; otherwise, the characters from the vector are delivered
+to the screen instead of the original character.
 
 For example, (aset buffer-display-table ?X ?Y) will cause Emacs to display
 a capital Y instead of each X character.
@@ -5827,7 +5828,7 @@ cursor type.  */);
                      &current_buffer->scroll_up_aggressively, Qnil,
                      doc: /* How far to scroll windows upward.
 If you move point off the bottom, the window scrolls automatically.
-This variable controls how far it scrolls.  nil, the default,
+This variable controls how far it scrolls.  The value nil, the default,
 means scroll to center point.  A fraction means scroll to put point
 that fraction of the window's height from the bottom of the window.
 When the value is 0.0, point goes at the bottom line, which in the simple
@@ -5840,7 +5841,7 @@ between 0.0 and 1.0, inclusive.  */);
                      &current_buffer->scroll_down_aggressively, Qnil,
                      doc: /* How far to scroll windows downward.
 If you move point off the top, the window scrolls automatically.
-This variable controls how far it scrolls.  nil, the default,
+This variable controls how far it scrolls.  The value nil, the default,
 means scroll to center point.  A fraction means scroll to put point
 that fraction of the window's height from the top of the window.
 When the value is 0.0, point goes at the top line, which in the simple
@@ -6031,7 +6032,7 @@ is a member of the list.  */);
   Vinhibit_read_only = Qnil;
 
   DEFVAR_PER_BUFFER ("cursor-type", &current_buffer->cursor_type, Qnil,
-     doc: /* Cursor to use when this buffer is in the selected window.
+                     doc: /* Cursor to use when this buffer is in the selected window.
 Values are interpreted as follows:
 
   t               use the cursor specified for the frame
@@ -6056,11 +6057,13 @@ to the default frame line height.  A value of nil means add no extra space.  */)
 
   DEFVAR_PER_BUFFER ("cursor-in-non-selected-windows",
                      &current_buffer->cursor_in_non_selected_windows, Qnil,
-    doc: /* *Cursor type to display in non-selected windows.
+                     doc: /* *Cursor type to display in non-selected windows.
 The value t means to use hollow box cursor.  See `cursor-type' for other values.  */);
 
   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;
 
   DEFVAR_LISP ("change-major-mode-hook", &Vchange_major_mode_hook,