(Killing Buffers): Update documentation of kill-buffer.

2 files changed, 9 insertions, 2 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index ff744560092..04fbf8716a6 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -5,6 +5,9 @@
         (Choosing Window): Rewrite documentation of display-buffer and
         its options.
 
+        * buffers.texi (Killing Buffers): Update documentation of
+        kill-buffer.
+
 2008-10-21  Eli Zaretskii  <eliz@gnu.org>
 
         * processes.texi (Serial Ports): Fix wording and improve markup.
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 4d12185726c..b915e69ab6a 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -996,10 +996,11 @@ this feature to test whether a buffer has been killed:
 @end group
 @end example
 
-@deffn Command kill-buffer buffer-or-name
+@deffn Command kill-buffer &optional buffer-or-name
 This function kills the buffer @var{buffer-or-name}, freeing all its
 memory for other uses or to be returned to the operating system.  If
-@var{buffer-or-name} is @code{nil}, it kills the current buffer.
+@var{buffer-or-name} is @code{nil} or omitted, it kills the current
+buffer.
 
 Any processes that have this buffer as the @code{process-buffer} are
 sent the @code{SIGHUP} signal, which normally causes them to terminate.
@@ -1012,6 +1013,9 @@ It does this even if not called interactively.  To prevent the request
 for confirmation, clear the modified flag before calling
 @code{kill-buffer}.  @xref{Buffer Modification}.
 
+This function calls `replace-buffer-in-windows' for cleaning up all
+windows currently displaying the buffer to be killed.
+
 Killing a buffer that is already dead has no effect.
 
 This function returns @code{t} if it actually killed the buffer.  It