[Emacs-diffs] emacs-24 r117450: src/xdisp.c (handle_stop): Improve commentary.

[Eli Zaretskii]

------------------------------------------------------------
revno: 117450
revision-id: address@hidden
parent: address@hidden
committer: Eli Zaretskii <address@hidden>
branch nick: emacs-24
timestamp: Mon 2014-08-18 18:38:56 +0300
message:
  src/xdisp.c (handle_stop): Improve commentary.
modified:
  src/ChangeLog                  changelog-20091113204419-o5vbwnq5f7feedwu-1438
  src/xdisp.c                    xdisp.c-20091113204419-o5vbwnq5f7feedwu-240

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2014-08-18 15:34:49 +0000
+++ b/src/ChangeLog     2014-08-18 15:38:56 +0000
@@ -1,5 +1,7 @@
 2014-08-18  Eli Zaretskii  <address@hidden>
 
+       * xdisp.c (handle_stop): Improve commentary.
+
        * indent.c (Fvertical_motion): Fix vertical motion up through a
        display property after a newline.  (Bug#18276)
 

=== modified file 'src/xdisp.c'
--- a/src/xdisp.c       2014-08-17 14:48:50 +0000
+++ b/src/xdisp.c       2014-08-18 15:38:56 +0000
@@ -3414,6 +3414,48 @@
   if (it->selective_display_ellipsis_p)
     it->saved_face_id = it->face_id;
 
+  /* Here's the description of the semantics of, and the logic behind,
+     the various HANDLED_* statuses:
+
+     HANDLED_NORMALLY means the handler did its job, and the loop
+     should proceed to calling the next handler in order.
+
+     HANDLED_RECOMPUTE_PROPS means the handler caused a significant
+     change in the properties and overlays at current position, so the
+     loop should be restarted, to re-invoke the handlers that were
+     already called.  This happens when fontification-functions were
+     called by handle_fontified_prop, and actually fontified
+     something.  Another case where HANDLED_RECOMPUTE_PROPS is
+     returned is when we discover overlay strings that need to be
+     displayed right away.  The loop below will continue for as long
+     as the status is HANDLED_RECOMPUTE_PROPS.
+
+     HANDLED_RETURN means return immediately to the caller, to
+     continue iteration without calling any further handlers.  This is
+     used when we need to act on some property right away, for example
+     when we need to display the ellipsis or a replacing display
+     property, such as display string or image.
+
+     HANDLED_OVERLAY_STRING_CONSUMED means an overlay string was just
+     consumed, and the handler switched to the next overlay string.
+     This signals the loop below to refrain from looking for more
+     overlays before all the overlay strings of the current overlay
+     are processed.
+
+     Some of the handlers called by the loop push the iterator state
+     onto the stack (see 'push_it'), and arrange for the iteration to
+     continue with another object, such as an image, a display string,
+     or an overlay string.  In most such cases, it->stop_charpos is
+     set to the first character of the string, so that when the
+     iteration resumes, this function will immediately be called
+     again, to examine the properties at the beginning of the string.
+
+     When a display or overlay string is exhausted, the iterator state
+     is popped (see 'pop_it'), and iteration continues with the
+     previous object.  Again, in many such cases this function is
+     called again to find the next position where properties might
+     change.  */
+
   do
     {
       handled = HANDLED_NORMALLY;