documentation of overlays-at is confusing

[Joe Wells]

The documentation of the overlays-at function says:

  Return a list of the overlays that contain position pos.

This is unclear on what is meant by “contain position pos”.  A
straightforward reading of this would lead one to believe that an
overlay that begins or ends at pos would “contain pos”.

However, it seems that the actual behavior is that it returns overlays
which contain the _character_at_pos_.  For example, evaluating the
following expression returns nil:

  (let ((buf (get-buffer-create "foo")))
    (with-current-buffer buf
      (display-buffer buf)
      (erase-buffer)
      (dolist (o (overlays-in (point-min) (point-max)))
        (delete-overlay o))
      (make-overlay (point-min) (point-min))
      (overlays-at (point-min))))

The confusion is between the notion of positions that are beginnings
and endings of pieces of text and positions of characters in text.
These are two distinct notions of “position”.

It would be useful if the documentation were clarified on this point.

I hope this report is helpful.

Joe

======================================================================
In GNU Emacs 22.1.1 (i686-pc-linux-gnu, GTK+ Version 2.8.20)
 of 2007-06-27 on artemis
Windowing system distributor `The X.Org Foundation', version 11.0.70000000
configured using `configure  '--prefix=/home/jbw/local2' '--enable-debug' 
'--disable-nls' '--with-x-toolkit=gtk' 'CFLAGS=-O0 -g3 -ggdb''

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: en_US.UTF-8
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: jbw
  value of $LANG: nil
  locale-coding-system: utf-8
  default-enable-multibyte-characters: t

Major mode: Lisp Interaction

Minor modes in effect:
  TeX-source-specials-mode: t
  auto-fill-function: do-auto-fill
  shell-dirtrack-mode: t
  outline-minor-mode: t
  desktop-save-mode: t
  url-handler-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  unify-8859-on-encoding-mode: t
  utf-translate-cjk-mode: t
  auto-compression-mode: t
  temp-buffer-resize-mode: t
  size-indication-mode: t
  line-number-mode: t
  transient-mark-mode: t