(compilation-find-buffer): Return current buffer immediately if suitable.

(compile, compilation-buffer-name, compilation-start): Doc fixes.

2 files changed, 28 insertions, 13 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 66f1618be60..cdb89b36942 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,9 @@
+2007-08-02  Richard Stallman  <rms@gnu.org>
+
+        * progmodes/compile.el (compilation-find-buffer): Return current
+        buffer immediately if suitable.
+        (compile, compilation-buffer-name, compilation-start): Doc fixes.
+
 2007-08-02  Stefan Monnier  <monnier@iro.umontreal.ca>
 
         * vc-bzr.el (vc-bzr-admin-dirstate): Rename from `...-dirname'.
@@ -10,7 +16,7 @@
 
         * ibuf-ext.el (ibuffer-mark-old-buffers): Docstring fix.
 
-2007-07-31  Drew Adams  <drew.adams@oracle.com>  (tiny change)
+2007-07-31  Drew Adams  <drew.adams@oracle.com>
 
         * cus-edit.el (custom-group-value-create, custom-goto-parent):
         Fix parent groups link.
@@ -12319,7 +12325,7 @@
         (name, size, mode) <define-ibuffer-column>: Add a header-mouse-map
         property.
 
-2006-04-02  Drew Adams  <drew.adams@oracle.com>  (tiny change)
+2006-04-02  Drew Adams  <drew.adams@oracle.com>
 
         * speedbar.el (speedbar-after-create-hook): Doc fix.
 
diff --git a/lisp/progmodes/compile.el b/lisp/progmodes/compile.el
index 13e4e40044b..529194ffa7e 100644
--- a/lisp/progmodes/compile.el
+++ b/lisp/progmodes/compile.el
@@ -888,11 +888,13 @@ non-nil; otherwise uses `compile-command'.  With prefix arg, always prompts.
 Additionally, with universal prefix arg, compilation buffer will be in
 comint mode, i.e. interactive.
 
-To run more than one compilation at once, start one and rename
+To run more than one compilation at once, start one then rename
 the \`*compilation*' buffer to some other name with
-\\[rename-buffer].  Then start the next one.  On most systems,
-termination of the main compilation process kills its
-subprocesses.
+\\[rename-buffer].  Then _switch buffers_ and start the new compilation.
+It will create a new \`*compilation*' buffer.
+
+On most systems, termination of the main compilation process
+kills its subprocesses.
 
 The name used for the buffer is actually whatever is returned by
 the function in `compilation-buffer-name-function', so you can set that
@@ -944,7 +946,7 @@ visible rather than the beginning."
 If NAME-FUNCTION is non-nil, call it with one argument MODE-NAME
 to determine the buffer name.
 Likewise if `compilation-buffer-name-function' is non-nil.
-If current buffer is the mode MODE-COMMAND,
+If current buffer has the major mode MODE-COMMAND,
 return the name of the current buffer, so that it gets reused.
 Otherwise, construct a buffer name from MODE-NAME."
   (cond (name-function
@@ -983,8 +985,11 @@ The rest of the arguments are optional; for them, nil means use the default.
 
 MODE is the major mode to set in the compilation buffer.  Mode
 may also be t meaning use `compilation-shell-minor-mode' under `comint-mode'.
+
 If NAME-FUNCTION is non-nil, call it with one argument (the mode name)
-to determine the buffer name.
+to determine the buffer name.  Otherwise, the default is to
+reuses the current buffer if it has the proper major mode,
+else use or create a buffer with name based on the major mode.
 
 If HIGHLIGHT-REGEXP is non-nil, `next-error' will temporarily highlight
 the matching section of the visited source line; the default is to use the
@@ -1604,12 +1609,16 @@ Use this command in a compilation log buffer.  Sets the mark at point there."
     (setq compilation-current-error (point))
     (next-error-internal)))
 
-;; Return a compilation buffer.
-;; If the current buffer is a compilation buffer, return it.
-;; Otherwise, look for a compilation buffer and signal an error
-;; if there are none.
 (defun compilation-find-buffer (&optional avoid-current)
-  (next-error-find-buffer avoid-current 'compilation-buffer-internal-p))
+  "Return a compilation buffer.
+If AVOID-CURRENT is nil, and
+the current buffer is a compilation buffer, return it.
+If AVOID-CURRENT is non-nil, return the current buffer
+only as a last resort."
+  (if (and (compilation-buffer-internal-p (current-buffer))
+           (not avoid-current))
+      (current-buffer)
+    (next-error-find-buffer avoid-current 'compilation-buffer-internal-p)))
 
 ;;;###autoload
 (defun compilation-next-error-function (n &optional reset)