bug#18636: 24.4.50; doc of `display-monitor-attributes-list' - DISPLAY? FRAME?

[Drew Adams]

I find it unclear that the optional parameter of
`display-monitor-attributes-list' is named DISPLAY, and is referred to
as a display in the doc string, and yet in `frame-monitor-attributes'
it is arg FRAME that is passed to `display-monitor-attributes-list'.

Is the argument of `display-monitor-attributes-list' a display or a
frame?

What about other functions, such as `display-pixel-height', which call
`display-monitor-attributes-list'?  They seem to pass their DISPLAY arg
to it.  Is this arg too something that can be (or is always?) a frame?
The doc string of `display-pixel-height' (for example) says:

  "If DISPLAY is omitted or nil, it defaults to the selected frame's
   display."

That would seem to suggest that a frame is not a display, but rather it
_has_ a display.

And there is a frame parameter `display', whose value is "The display on
which to open this frame.  It should be a string of the form
`"HOST:DPY.SCREEN"', just like the `DISPLAY' environment variable.

This suggests that a display is not a frame.  So how is it that
`frame-monitor-attributes' passes a FRAME to
`display-monitor-attributes-list', which supposedly expects a display
instead?

Please try to clear up some of this confusion in the doc and doc
strings.


In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-09-15 on LEG570
Bzr revision: 117884 dancol@dancol.org-20140915050944-sqsajysnwef51f9m
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking 'CFLAGS=-O0 -g3' CPPFLAGS=-DGLYPH_DEBUG=1'