; Fix the documentation of 'overlays-in' etc.

* src/buffer.c (Foverlays_in):
* lisp/subr.el (remove-overlays):
* doc/lispref/display.texi (Finding Overlays, Managing Overlays):
* etc/NEWS: Improve the documentation of recent changes in
behavior of 'overlays-in' and 'remove-overlays'.  (Bug#80242)

doc/lispref/display.texi

@@ -1710,6 +1710,12 @@ be altered so that they start at @var{end}.
 Overlays that start before @var{start} and end after @var{end} will be
 split into two overlays: one that ends at @var{start} and the other that
 begins at @var{end}.
+
+@item
+Empty overlays (@pxref{empty overlays}) will be removed if they are
+either at @var{start}, or strictly between @var{start} and @var{end}
+excluding @var{end}, or at @var{end} when @var{end} denotes the position
+at the end of the buffer.
 @end itemize
 
 If @var{name} is omitted or @code{nil}, it means to delete/modify all
@@ -2145,7 +2151,10 @@ 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.)
+@var{end} you could increment the @var{end} position instead.)  Note
+that if @var{beg} and @var{end} are the same position, an empty overlay
+that is at @var{beg} is also at @var{end}, so this case is somewhat
+similar to an empty overlay at the end of the buffer.
 
 The order in which the overlays appear in the returned list is
 unpredictable.

etc/NEWS

@@ -3936,12 +3936,15 @@ 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.
++++ Original behavior of 'overlays-in' and 'overlays-at' has been
+restored.  Before Emacs 28.1, the list of overlays returned by these two
+functions included overlays outside of the current narrowing of the
+buffer, and there wasn't a special exception for including empty
+overlays at end of accessible portion of the buffer.  This behavior has
+been restored, and the special behavior for empty overlays is again
+reserved only to the actual end of buffer, disregarding the narrowing.
+As result, 'remove-overlays' can now again remove overlays outside of
+the narrowing, as it did before Emacs 28.1.
 
 ---
 ** 'help-setup-xref' now re-enables the major mode of the Help buffer.

lisp/subr.el

@@ -4451,6 +4451,10 @@ at BEG.  Likewise, if the targeted overlays end after END, they
 will be altered so that they start at END.  Overlays that start
 at or after BEG and end before END will be removed completely.
 
+Empty overlays will be removed if they are at BEG, between BEG
+and END, or at END provided END denotes the position at the end
+of the buffer.
+
 BEG and END default respectively to the beginning and end of the
 buffer.
 Values are compared with `eq'.

src/buffer.c

@@ -3927,7 +3927,9 @@ END.
 
 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.
+END denotes the position at the end of the buffer.  (If BEG and END are the
+same buffer position, an empty overlay at BEG will also be at END, but it
+still qualifies because it's at BEG.)
 
 The resulting list of overlays is in an arbitrary unpredictable order.