1 files changed, 10 insertions, 2 deletions

diff --git a/src/dispextern.h b/src/dispextern.h
index b877bf9965a..6e070f3dbef 100644
--- a/src/dispextern.h
+++ b/src/dispextern.h
@@ -2205,7 +2205,11 @@ struct it
   struct display_pos current;
 
   /* Total number of overlay strings to process.  This can be >
-     OVERLAY_STRING_CHUNK_SIZE.  */
+     OVERLAY_STRING_CHUNK_SIZE.  Value is dependable only when
+     current.overlay_string_index >= 0.  Use the latter to determine
+     whether an overlay string is being iterated over, because
+     n_overlay_strings can be positive even when we are not rendering
+     an overlay string.  */
   ptrdiff_t n_overlay_strings;
 
   /* The charpos where n_overlay_strings was calculated.  This should
@@ -2224,7 +2228,8 @@ struct it
 
   /* If non-nil, a Lisp string being processed.  If
      current.overlay_string_index >= 0, this is an overlay string from
-     pos.  */
+     pos.  Use STRINGP (it.string) to test whether we are rendering a
+     string or something else; do NOT use BUFFERP (it.object).  */
   Lisp_Object string;
 
   /* If non-nil, we are processing a string that came
@@ -2413,6 +2418,9 @@ struct it
      and continuation glyphs, or blanks that extend each line to the
      edge of the window on a TTY.
 
+     Do NOT use !BUFFERP (it.object) as a test whether we are
+     iterating over a string; use STRINGP (it.string) instead.
+
      Position is the current iterator position in object.  */
   Lisp_Object object;
   struct text_pos position;