Improve commentary regarding redisplay.

1 files changed, 16 insertions, 7 deletions

diff --git a/src/dispextern.h b/src/dispextern.h
index 00da256c43e..b0a072f71f8 100644
--- a/src/dispextern.h
+++ b/src/dispextern.h
@@ -2222,13 +2222,22 @@ struct it
      MODE_LINE_FACE_ID, etc, depending on what we are displaying.  */
   int base_face_id;
 
-  /* If what == IT_CHARACTER, character and length in bytes.  This is
-     a character from a buffer or string.  It may be different from
-     the character displayed in case that
-     unibyte_display_via_language_environment is set.
-
-     If what == IT_COMPOSITION, the first component of a composition
-     and length in bytes of the composition.  */
+  /* If `what' == IT_CHARACTER, the character and the length in bytes
+     of its multibyte sequence.  The character comes from a buffer or
+     a string.  It may be different from the character displayed in
+     case that unibyte_display_via_language_environment is set.
+
+     If `what' == IT_COMPOSITION, the first component of a composition
+     and length in bytes of the composition.
+
+     If `what' is anything else, these tow are undefined (will
+     probably hold values for the last IT_CHARACTER or IT_COMPOSITION
+     traversed by the iterator.
+
+     The values are updated by get_next_display_element, so they are
+     out of sync with the value returned by IT_CHARPOS between the
+     time set_iterator_to_next advances the position and the time
+     get_next_display_element loads the new values into c and len.  */
   int c, len;
 
   /* If what == IT_COMPOSITION, iterator substructure for the