documentation of `buffer-list' misleading

[Matt Swift <swift@alum.mit.edu>]

This bug report will be sent to the Free Software Foundation,
not to your local site managers!
Please write in English, because the Emacs maintainers do not have
translators to read other languages for them.

Your bug report will be posted to the bug-gnu-emacs@gnu.org mailing list,
and to the gnu.emacs.bug news group.

In GNU Emacs 21.2.1 (i386-msvc-nt5.0.2195)
 of 2002-03-19 on buffy
configured using `configure --with-msvc (12.00)'
Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: ENU
  locale-coding-system: iso-latin-1
  default-enable-multibyte-characters: t

Please describe exactly what actions triggered the bug
and the precise symptoms of the bug:

The documentation of `buffer-list' in the docstring and the elisp manual v2.7
suggests that the following form in an interactive Lisp session
should always evaluate to t, but in fact it is usually not t:

(equal 
 (frame-parameter nil 'buffer-list)
 (buffer-list (selected-frame)))
 
 => nil

To make the apparent paradox clearer, one could write the equivalent form:

(equal 
 (frame-parameter (selected-frame) 'buffer-list)
 (buffer-list (selected-frame)))
 
 => nil

Looking at the source in buffer.c, I see that `(buffer-list my-frame)' is
returning a list of *all* buffers (that is, the same ones as `(buffer-list
nil)' returns) in the order that `other-buffer' is going to examine them when
my-frame is the selected frame.

Having the name of the function `buffer-list' seem associated with
`other-buffer' and not with the related but different frame parameter would be
ideal, in my opinion, but I realize that changing the names now would probably
cause more problems than it resolves.  Clearer documentation would suffice.

Recent input:
C-n C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p 
C-p C-p C-p C-p C-p C-p C-h i M-< t M-s b u f f e r 
- l i s t <return> <tab> C-a C-n C-n C-n C-n C-n C-n 
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-p M-x 
r e p o r t - e m a c s - b u g <return>

Recent messages:
Searching subfile elisp-19...
Searching subfile elisp-20...
Searching subfile elisp-21...
Searching subfile elisp-22...
Searching subfile elisp-23...
Searching subfile elisp-24...
Searching subfile elisp-25...
Searching subfile elisp-26...

Loading emacsbug...done