Minor doc and doc-string fixes (Bug#27091)

* src/window.c (Fset_window_scroll_bars): Fix doc-string.

* doc/lispref/display.texi (Fringe Size/Pos, Scroll Bars)
(Display Margins): Mention that `set-window-buffer' may override
settings made by `set-window-fringes', `set-window-scroll-bars'
and `set-window-margins'.
* doc/lispref/windows.texi (Buffers and Windows): Fix doc of
`set-window-buffer'.

3 files changed, 24 insertions, 11 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 51e31aa273f..aa75dcf5a0a 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3798,6 +3798,10 @@ fringe, and likewise @var{right} for the right fringe.  A value of
 @code{nil} for either one stands for the default width.  If
 @var{outside-margins} is non-@code{nil}, that specifies that fringes
 should appear outside of the display margins.
+
+The values specified here may be later overridden by invoking
+@code{set-window-buffer} (@pxref{Buffers and Windows}) on @var{window}
+with its @var{keep-margins} argument @code{nil} or omitted.
 @end defun
 
 @defun window-fringes &optional window
@@ -4200,7 +4204,8 @@ using the following function:
 
 @defun set-window-scroll-bars window &optional width vertical-type height horizontal-type
 This function sets the width and/or height and the types of scroll bars
-for window @var{window}.
+for window @var{window}.  If @var{window} is @code{nil}, the selected
+window is used.
 
 @var{width} specifies the width of the vertical scroll bar in pixels
 (@code{nil} means use the width specified for the frame).
@@ -4215,7 +4220,9 @@ vertical scroll bar.
 The possible values are @code{bottom}, @code{t}, which means to use the
 frame's default, and @code{nil} for no horizontal scroll bar.
 
-If @var{window} is @code{nil}, the selected window is used.
+The values specified here may be later overridden by invoking
+@code{set-window-buffer} (@pxref{Buffers and Windows}) on @var{window}
+with its @var{keep-margins} argument @code{nil} or omitted.
 @end defun
 
 The following four functions take as argument a live window which
@@ -4759,6 +4766,10 @@ Thus, you can make changes take effect by calling
 This function specifies the margin widths for window @var{window}, in
 character cell units.  The argument @var{left} controls the left
 margin, and @var{right} controls the right margin (default @code{0}).
+
+The values specified here may be later overridden by invoking
+@code{set-window-buffer} (@pxref{Buffers and Windows}) on @var{window}
+with its @var{keep-margins} argument @code{nil} or omitted.
 @end defun
 
 @defun window-margins &optional window
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index b015233753f..3a9257e05af 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -2049,8 +2049,8 @@ signals an error.  @xref{Dedicated Windows}.
 By default, this function resets @var{window}'s position, display
 margins, fringe widths, and scroll bar settings, based on the local
 variables in the specified buffer.  However, if the optional argument
-@var{keep-margins} is non-@code{nil}, it leaves the display margins
-and fringe widths unchanged.
+@var{keep-margins} is non-@code{nil}, it leaves @var{window}'s display
+margins, fringes and scroll bar settings alone.
 
 When writing an application, you should normally use the higher-level
 functions described in @ref{Switching Buffers}, instead of calling
diff --git a/src/window.c b/src/window.c
index fc9f40222bb..bf89f0e488b 100644
--- a/src/window.c
+++ b/src/window.c
@@ -3342,7 +3342,7 @@ run_window_size_change_functions (Lisp_Object frame)
 /* Make WINDOW display BUFFER.  RUN_HOOKS_P means it's allowed
    to run hooks.  See make_frame for a case where it's not allowed.
    KEEP_MARGINS_P means that the current margins, fringes, and
-   scroll-bar settings of the window are not reset from the buffer's
+   scroll bar settings of the window are not reset from the buffer's
    local settings.  */
 
 void
@@ -7045,16 +7045,18 @@ DEFUN ("set-window-scroll-bars", Fset_window_scroll_bars,
 WINDOW must be a live window and defaults to the selected one.
 
 Second parameter WIDTH specifies the pixel width for the vertical scroll
-bar.  If WIDTH is nil, use the scroll-bar width of WINDOW's frame.
+bar.  If WIDTH is nil, use the scroll bar width of WINDOW's frame.
 Third parameter VERTICAL-TYPE specifies the type of the vertical scroll
-bar: left, right, or nil.  If VERTICAL-TYPE is t, this means use the
-frame's scroll-bar type.
+bar: left, right, nil or t where nil means to not display a vertical
+scroll bar on WINDOW and t means to use WINDOW frame's vertical scroll
+bar type.
 
 Fourth parameter HEIGHT specifies the pixel height for the horizontal
-scroll bar.  If HEIGHT is nil, use the scroll-bar height of WINDOW's
+scroll bar.  If HEIGHT is nil, use the scroll bar height of WINDOW's
 frame.  Fifth parameter HORIZONTAL-TYPE specifies the type of the
-horizontal scroll bar: nil, bottom, or t.  If HORIZONTAL-TYPE is t, this
-means to use the frame's horizontal scroll-bar type.
+horizontal scroll bar: bottom, nil, or t where nil means to not display
+a horizontal scroll bar on WINDOW and t means to use WINDOW frame's
+horizontal scroll bar type.
 
 Return t if scroll bars were actually changed and nil otherwise.  */)
   (Lisp_Object window, Lisp_Object width, Lisp_Object vertical_type,