Subject: 29.0.60; overlay-lists does not conform to its docstring

From: Kai Ma <[email-masked]>
Date: Wed, 14 Dec 2022 13:22:07 +0800

The docstring of overlay-lists states that the return value is a cons
pair, and the CDR is not always nil.  However, the code does not do what
it claims to do.

    DEFUN ("overlay-lists", Foverlay_lists, Soverlay_lists, 0, 0, 0,
           doc: /* Return a pair of lists giving all the overlays of the current buffer.
    The car has all the overlays before the overlay center;
    the cdr has all the overlays after the overlay center.
    Recentering overlays moves overlays between these lists.
    The lists you get are copies, so that changing them has no effect.
    However, the overlays you get are the real objects that the buffer uses. */)
      (void)
    {
      Lisp_Object overlays = Qnil;
      struct itree_node *node;
    
      ITREE_FOREACH (node, current_buffer->overlays, BEG, Z, DESCENDING)
        overlays = Fcons (node->data, overlays);
    
      return Fcons (overlays, Qnil);
    }

This change in behavior has led to at least one breakage in the wild:
symbol-overlay cannot count overlays correctly.

I think there is a problem either in the code or in the docstring.

	Kai