Doc fixes related to fit-frame-to-buffer

* lisp/window.el (fit-frame-to-buffer-bottom-margin)
(fit-frame-to-buffer, fit-window-to-buffer): Doc fixes.

* etc/NEWS: Related edit.

3 files changed, 26 insertions, 11 deletions

diff --git a/etc/NEWS b/etc/NEWS
index 42e773b2a03..3bd4ebae4fa 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -851,8 +851,12 @@ now accept a third argument to avoid choosing the selected window.
 *** `temp-buffer-resize-mode' no longer resizes windows that have been
 reused.
 
-*** New function `fit-frame-to-buffer' and new options
-`fit-frame-to-buffer' and `fit-frame-to-buffer-bottom-margin'.
+*** New command `fit-frame-to-buffer' adjusts the frame height to
+fit the contents.
+
+*** The command `fit-window-to-buffer' can adjust the frame height
+if the new option `fit-frame-to-buffer' is non-nil.
+
 +++
 *** New option switch-to-buffer-preserve-window-point to restore a
 window's point when switching buffers.
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index a62288dd29a..74d66809d55 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,5 +1,8 @@
 2012-11-16  Glenn Morris  <rgm@gnu.org>
 
+        * window.el (fit-frame-to-buffer-bottom-margin)
+        (fit-frame-to-buffer, fit-window-to-buffer): Doc fixes.
+
         * faces.el (face-underline-p): Use face-attribute-specified-or.
 
 2012-11-15  Juanma Barranquero  <lekktu@gmail.com>
diff --git a/lisp/window.el b/lisp/window.el
index 6ea66d9d0a2..c9ea8351e8c 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -6074,22 +6074,26 @@ of `fit-frame-to-buffer-max-height' and `window-min-height'."
   :group 'help)
 
 (defcustom fit-frame-to-buffer-bottom-margin 4
-  "Bottom margin for `fit-frame-to-buffer'.
-This is the number of lines `fit-frame-to-buffer' leaves free at the
-bottom of the display in order to not obscure the system task bar."
+  "Bottom margin for the command `fit-frame-to-buffer'.
+This is the number of lines that function leaves free at the bottom of
+the display, in order to not obscure any system task bar or panel.
+If you do not have one (or if it is vertical) you might want to
+reduce this.  If it is thicker, you might want to increase this."
+  ;; If you set this too small, fit-frame-to-buffer can shift the
+  ;; frame up to avoid the panel.
   :type 'integer
   :version "24.3"
   :group 'windows)
 
 (defun fit-frame-to-buffer (&optional frame max-height min-height)
-  "Adjust height of FRAME to display its buffer's contents exactly.
+  "Adjust height of FRAME to display its buffer contents exactly.
 FRAME can be any live frame and defaults to the selected one.
 
-Optional argument MAX-HEIGHT specifies the maximum height of
-FRAME and defaults to the height of the display below the current
-top line of FRAME minus FIT-FRAME-TO-BUFFER-BOTTOM-MARGIN.
-Optional argument MIN-HEIGHT specifies the minimum height of
-FRAME."
+Optional argument MAX-HEIGHT specifies the maximum height of FRAME.
+It defaults to the height of the display below the current
+top line of FRAME, minus `fit-frame-to-buffer-bottom-margin'.
+Optional argument MIN-HEIGHT specifies the minimum height of FRAME.
+The default corresponds to `window-min-height'."
   (interactive)
   (setq frame (window-normalize-frame frame))
   (let* ((root (frame-root-window frame))
@@ -6166,6 +6170,10 @@ defaults to `window-min-height'.  Both MAX-HEIGHT and MIN-HEIGHT
 are specified in lines and include the mode line and header line,
 if any.
 
+If WINDOW is a full height window, then if the option
+`fit-frame-to-buffer' is non-nil, this calls the function
+`fit-frame-to-buffer' to adjust the frame height.
+
 Return the number of lines by which WINDOW was enlarged or
 shrunk.  If an error occurs during resizing, return nil but don't
 signal an error.