Improve documentation of set-window-start

* doc/lispref/windows.texi (Window Start and End):
* src/window.c (Fset_window_start): Document that reliable
setting of a window start position requires to adjust point to
be visible.  (Bug#34038)

1 files changed, 6 insertions, 1 deletions

diff --git a/src/window.c b/src/window.c
index 04183abb7c5..dfac3b5b879 100644
--- a/src/window.c
+++ b/src/window.c
@@ -1704,7 +1704,12 @@ DEFUN ("set-window-start", Fset_window_start, Sset_window_start, 2, 3, 0,
        doc: /* Make display in WINDOW start at position POS in WINDOW's buffer.
 WINDOW must be a live window and defaults to the selected one.  Return
 POS.  Optional third arg NOFORCE non-nil inhibits next redisplay from
-overriding motion of point in order to display at this exact start.  */)
+overriding motion of point in order to display at this exact start.
+
+For reliable setting of WINDOW start position, make sure point is
+at a position that will be visible when that start is in effect,
+otherwise there's a chance POS will be disregarded, e.g., if point
+winds up in a partially-visible line.  */)
   (Lisp_Object window, Lisp_Object pos, Lisp_Object noforce)
 {
   register struct window *w = decode_live_window (window);