Adjust documentation to changes in 'overlays-in' and 'overlays-at'

* src/buffer.c (overlays_in): Fix commentary to match the code.
(Foverlays_in, Foverlays_at): Doc fixes.  (Bug#80242)

* test/src/buffer-tests.el (test-overlays-at-2): Add one test.

* doc/lispref/display.texi (Finding Overlays): Update and improve
the documentation of 'overlays-in' and 'overlays-at'.

* etc/NEWS: Announce the changes.

doc/lispref/display.texi

@@ -1625,6 +1625,7 @@ current buffer.
 
 @cindex empty overlay
 @cindex overlay, empty
+@anchor{empty overlays}
 An overlay whose @var{start} and @var{end} specify the same buffer
 position is known as @dfn{empty}.  A non-empty overlay can become
 empty if the text between its @var{start} and @var{end} is deleted.
@@ -2056,12 +2057,11 @@ line at display-time.  @xref{Truncation}.
 @kindex evaporate @r{(overlay property)}
 @item evaporate
 If this property is non-@code{nil}, the overlay is deleted automatically
-if it becomes empty (i.e., if its length becomes zero).  If you give
-an empty overlay (@pxref{Managing Overlays, empty overlay}) a
-non-@code{nil} @code{evaporate} property, that deletes it immediately.
-Note that, unless an overlay has this property, it will not be deleted
-when the text between its starting and ending positions is deleted
-from the buffer.
+if it becomes empty (i.e., if its length becomes zero).  If you give an
+empty overlay (@pxref{empty overlays}) a non-@code{nil} @code{evaporate}
+property, that deletes it immediately.  Note that, unless an overlay has
+this property, it will not be deleted when the text between its starting
+and ending positions is deleted from the buffer.
 
 @kindex display-line-numbers-disable @r{(overlay property)}
 @item display-line-numbers-disable
@@ -2103,11 +2103,11 @@ Properties}.
 @cindex overlays, searching for
 
 @defun overlays-at pos &optional sorted
-This function returns a list of all the overlays that cover the character at
+This function returns a list of all the overlays that contain the character at
 position @var{pos} in the current buffer.  If @var{sorted} is non-@code{nil},
-the list is in decreasing order of priority, otherwise it is in no particular
-order.  An overlay contains position @var{pos} if it begins at or before
-@var{pos}, and ends after @var{pos}.
+the returned list is in decreasing order of priority, otherwise it is in no
+particular order.  An overlay contains the character at @var{pos} if it begins
+at or before @var{pos}, and ends after @var{pos}.
 
 To illustrate usage, here is a Lisp function that returns a list of the
 overlays that specify property @var{prop} for the character at point:
@@ -2123,16 +2123,36 @@ overlays that specify property @var{prop} for the character at point:
       (setq overlays (cdr overlays)))
     found))
 @end smallexample
+
+Empty overlays (@pxref{empty overlays}) do not contain any characters,
+so this function does not return them.  Use @code{overlays-in},
+described below, instead if empty overlays are of interest.
+
+Note that this function can return overlays outside of the current
+narrowing of the buffer (@pxref{Narrowing}) if @var{pos} is outside of
+the narrowing.
 @end defun
 
 @defun overlays-in beg end
-This function returns a list of the overlays that overlap the region
+This function returns a list of the overlays that overlap with the region
 @var{beg} through @var{end}.  An overlay overlaps with a region if it
-contains one or more characters in the region; empty overlays
-(@pxref{Managing Overlays, empty overlay}) overlap if they are at
-@var{beg}, strictly between @var{beg} and @var{end}, or at @var{end}
-when @var{end} denotes the position at the end of the accessible part
-of the buffer.
+contains one or more characters between @var{beg} and @var{end}; this
+excludes the characters at (i.e.@: after) @var{end}.
+
+Empty overlays do not contain any characters, so the rule for including
+them is different: they are said to overlap if they are at @var{beg},
+strictly between @var{beg} and @var{end} excluding @var{end}, or at
+@var{end} when @var{end} denotes the position at the end of the buffer.
+(The special handling of empty overlays at end of buffer is to allow
+such overlays to be found and processed.  For any other value of
+@var{end} you could increment the @var{end} position instead.)
+
+The order in which the overlays appear in the returned list is
+unpredictable.
+
+Note that this function can return overlays outside of the current
+narrowing of the buffer if @var{beg} and/or @var{end} are outside of
+the narrowing.
 @end defun
 
 @defun next-overlay-change pos

etc/NEWS

@@ -3814,6 +3814,13 @@ display time or even cause Emacs to hang trying to display such a face.
 Affected APIs include 'defface', 'set-face-attribute', their callers,
 and other similar functions.
 
++++
+Original behavior of 'overlays-in' and 'overlays-at' has been restored.
+Before Emacs 29.1, the list of overlays returned by these two functions
+included overlays outside of the current narrowing of the buffer.  This
+behavior has been restored.  As result, 'remove-overlays' can now again
+remove overlays outside of the narrowing, as it did before Emacs 29.1.
+
 ---
 ** 'help-setup-xref' now re-enables the major mode of the Help buffer.
 As a result, in many cases the buffer will be read-only afterwards.

src/buffer.c

@@ -3052,18 +3052,20 @@ the normal hook `change-major-mode-hook'.  */)
 /* Find all the overlays in the current buffer that overlap the range
    [BEG, END).
 
-   If EMPTY is true, include empty overlays in that range and also at
-   END, provided END denotes the position at the end of the accessible
-   part of the buffer.
-
-   If TRAILING is true, include overlays that begin at END, provided
-   END denotes the position at the end of the accessible part of the
+   If EMPTY is true, include empty overlays in that range and also
+   those at END, provided END denotes the position at the end of the
    buffer.
 
+   If TRAILING is true, include overlays that begin at ZV.
+   (FIXME: This argument is nowadays effectively ignored, since the code
+   no longer pays any attention to ZV.  We basically rely on the caller
+   to ensure that TRAILING is only true when END > ZV.  This happens, e.g.,
+   when we are called from overlays_at with BEG = ZV and END = ZV + 1.)
+
    Return the number found, and store them in a vector in *VEC_PTR.
    Store in *LEN_PTR the size allocated for the vector.
    Store in *NEXT_PTR the next position after POS where an overlay starts,
-     or ZV if there are no more overlays.
+     or Z if there are no more overlays after POS.
    NEXT_PTR may be 0, meaning don't store that info.
 
    *VEC_PTR and *LEN_PTR should contain a valid vector and size
@@ -3875,9 +3877,12 @@ DEFUN ("overlays-at", Foverlays_at, Soverlays_at, 1, 2, 0,
        doc: /* Return a list of the overlays that contain the character at POS.
 If SORTED is non-nil, then sort them by decreasing priority.
 
-Zero-length overlays that start and stop at POS are not included in
-the return value.  Instead use `overlays-in' if those overlays are of
-interest.  */)
+Zero-length (a.k.a. "empty") overlays that start and stop at POS are not
+included in the return value.  Use `overlays-in' if empty overlays are of
+interest.
+
+This function can return overlays outside of the current narrowing of
+the buffer if POS is outside of the narrowing.  */)
   (Lisp_Object pos, Lisp_Object sorted)
 {
   ptrdiff_t len, noverlays;
@@ -3916,14 +3921,18 @@ interest.  */)
 
 DEFUN ("overlays-in", Foverlays_in, Soverlays_in, 2, 2, 0,
        doc: /* Return a list of the overlays that overlap the region BEG ... END.
-Overlap means that at least one character is contained within the overlay
-and also contained within the specified region.
+Overlap means that at least one character between BEG and END is contained
+within the overlay.  Note that this excludes the character at (i.e., after)
+END.
 
-Empty overlays are included in the result if they are located at BEG,
-between BEG and END, or at END provided END denotes the position at the
-end of the accessible part of the buffer.
+Empty overlays do not contain any characters, so they are included in the
+result if they are located at BEG, between BEG and END, or at END provided
+END denotes the position at the end of the buffer.
 
-The resulting list of overlays is in an arbitrary unpredictable order.  */)
+The resulting list of overlays is in an arbitrary unpredictable order.
+
+This function can return overlays outside of the current narrowing of
+the buffer if BEG and/or END are outside of the narrowing.  */)
   (Lisp_Object beg, Lisp_Object end)
 {
   ptrdiff_t len, noverlays;

test/src/buffer-tests.el

@@ -905,6 +905,7 @@ should evaporate overlays in both."
       (should-length 1 (overlays-at 10))
       (should-length 1 (overlays-at 20))
       (should-length 0 (overlays-at (point-max)))
+      (should-length 1 (overlays-at (1- (point-max))))
       (narrow-to-region 10 20)
       (should-length 1 (overlays-at (point-min)))
       (should-length 1 (overlays-at 15))