xdisp.c: Improve doc of `redisplay` flags a bit

2 files changed, 12 insertions, 4 deletions

diff --git a/src/window.h b/src/window.h
index 2f793ebe438..9da6126c321 100644
--- a/src/window.h
+++ b/src/window.h
@@ -1114,9 +1114,11 @@ void set_window_buffer (Lisp_Object window, Lisp_Object buffer,
 
 extern Lisp_Object echo_area_window;
 
-/* Non-zero if we should redraw the mode lines on the next redisplay.
+/* Non-zero if we should redraw the mode line*s* on the next redisplay.
    Usually set to a unique small integer so we can track the main causes of
-   full redisplays in `redisplay--mode-lines-cause'.  */
+   full redisplays in `redisplay--mode-lines-cause'.
+   Here "mode lines" includes other elements not coming from the buffer's
+   text, such as header-lines, tab lines, frame names, menu-bars, ....  */
 
 extern int update_mode_lines;
 
@@ -1134,6 +1136,11 @@ extern int windows_or_buffers_changed;
 extern void wset_redisplay (struct window *w);
 extern void fset_redisplay (struct frame *f);
 extern void bset_redisplay (struct buffer *b);
+
+/* Routines to indicate that the mode-lines might need to be redisplayed.
+   Just as for `update_mode_lines`, this includes other elements not coming
+   from the buffer's text, such as header-lines, tab lines, frame names,
+   menu-bars, ....   */
 extern void bset_update_mode_line (struct buffer *b);
 extern void wset_update_mode_line (struct window *w);
 /* Call this to tell redisplay to look for other windows than selected-window
diff --git a/src/xdisp.c b/src/xdisp.c
index a3464c2c375..5d94dc003f3 100644
--- a/src/xdisp.c
+++ b/src/xdisp.c
@@ -16490,8 +16490,9 @@ redisplay_internal (void)
   enum {MAX_GARBAGED_FRAME_RETRIES = 2 };
   int garbaged_frame_retries = 0;
 
-  /* True means redisplay has to consider all windows on all
-     frames.  False, only selected_window is considered.  */
+  /* False means that only the selected_window needs to be updated.
+     True means that other windows may need to be updated as well,
+     so we need to consult `needs_no_update` for all windows.  */
   bool consider_all_windows_p;
 
   /* True means redisplay has to redisplay the miniwindow.  */