A question about overlay-modification

[Joakim Jalap]

Hello Emacs devs!

I'm trodding along with my overlays rewrite, and the turn has come to
`report_overlay_modification'. I'm having a bit of a hard time parsing
the docstring and the code. The docstring says the following:

/* Run the modification-hooks of overlays that include
   any part of the text in START to END.
   If this change is an insertion, also
   run the insert-before-hooks of overlay starting at END,
   and the insert-after-hooks of overlay ending at START.

   This is called both before and after the modification.
   AFTER is true when we call after the modification.

   ARG1, ARG2, ARG3 are arguments to pass to the hook functions.
   When AFTER is nonzero, they are the start position,
   the position after the inserted new text,
   and the length of deleted or replaced old text.  */

And the code does the following:

#+begin_src C
  ptrdiff_t startpos, endpos;
  Lisp_Object ostart, oend;

  XSETMISC (overlay, tail);

  ostart = OVERLAY_START (overlay);
  oend = OVERLAY_END (overlay);
  endpos = OVERLAY_POSITION (oend);
  if (XFASTINT (start) > endpos)
    break;
  startpos = OVERLAY_POSITION (ostart);
  if (insertion && (XFASTINT (start) == startpos
                    || XFASTINT (end) == startpos))
    {
      prop = Foverlay_get (overlay, Qinsert_in_front_hooks);
      if (!NILP (prop))
        add_overlay_mod_hooklist (prop, overlay);
    }
  if (insertion && (XFASTINT (start) == endpos
                    || XFASTINT (end) == endpos))
    {
      prop = Foverlay_get (overlay, Qinsert_behind_hooks);
      if (!NILP (prop))
        add_overlay_mod_hooklist (prop, overlay);
    }
#+end_src

To me that looks like the insert-in-front-hooks get run for overlays
which start either at START or END, not only those which start at
END. Likewise (but the other way around) for insert-behind-hooks.

This was introduced in commit 9115729ea3ea049e00e9e72cae09095c593e131a
back in 1995. Before that, it looked more like what I would have
expected.

What am I missing here? When I rewrite it I guess I'll make it match
what's there now since it's been there for more than 20 years, but I'd
just like to understand what's going on.

(As an aside, the doc string mentions insert-before-hooks and
insert-after-hooks, while the code has Qinsert_in_front_hooks and
Qinsert_behind_hooks. Is this intentional or just left overs?)

-- Joakim