defined-colors doc string doesn't describe nil FRAME

[Drew Adams]

emacs -Q
C-h f defined-colors gives this:

 defined-colors is a compiled Lisp function in `faces.el'.
 (defined-colors &optional FRAME)

 Return a list of colors supported for a particular frame.
 The argument FRAME specifies which frame to try.
 The value may be different for frames on different display types.
 If FRAME doesn't support colors, the value is nil.

The default case, when FRAME is nil, is not even mentioned.

It's also not clear to me why a user would have different frames on
different displays in the same Emacs session.  Why would someone not
use nil for FRAME (which I imagine means colors that are available on
all frames?)?

And in that case (FRAME=nil), shouldn't we just have a constant for
that, whose value is established at Emacs startup?  IOW, can the set
of colors that work on all frames change during an Emacs session? If
not, using a constant would save some recomputation of this long list.

In sum, I might not understand this function correctly, based on its
doc string. If I do understand it, then why don't we have a constant
for the nil FRAME case?


In GNU Emacs 22.0.50.1 (i386-mingw-nt5.1.2600)
 of 2006-03-20 on W2ONE
X server distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --cflags -Id:/g/include'

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: cp1252
  default-enable-multibyte-characters: t

Major mode: Dired by name

Minor modes in effect:
  encoded-kbd-mode: t
  tooltip-mode: t
  auto-compression-mode: t
  tool-bar-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
  line-number-mode: t

Recent input:
<down-mouse-1> <mouse-1> <help-echo> <help-echo> <help-echo>
<help-echo> <help-echo> <menu-bar> <help-menu> <re
port-emacs-bug>

Recent messages:
(C:\Emacs-22-2006-03-20\bin\emacs.exe -q --no-site-file --debug-init
C:\drews-lisp-20)
Loading encoded-kb...done
For information about the GNU Project and its goals, type C-h C-p.
Loading dired...
Loading regexp-opt...done
Loading dired...done
Loading emacsbug...done