bug#3602: 23.0.94; window-line-height problems

[Drew Adams]

The behavior of this function seems broken, at least for LINE =
mode-line or header-line. And the doc is not good.
 
Doc string of `window-line-height' says this:
 
"Return height of current line if LINE is omitted or nil.  Return
height of header or mode line if LINE is `header-line' and
`mode-line'."
 
That seems to say that if you have a header line, then you can get its
height in pixels this way (window-line-height 'header-line), and
similarly for mode-line. But that doesn't seem to work.
 
emacs -Q
(setq Info-use-header-line t)
C-h i
M-: (window-line-height 'header-line) returns nil
M-: (window-line-height 'mode-line) returns nil
 
This part of the doc string is incomprehensible to me:
 
"Return nil if window display is not up-to-date." What does that mean?
And then it says "In that case, use `pos-visible-in-window-p' to
obtain the information." How to do that? What args to use with
`pos-visible-in-window-p', to find out the `window-line-height' for
the header-line, for instance? This paragraph is quite unclear to me.
 
Also, the function is called *-height, and the first part of the doc
string says that it returns the "height in pixels". But later in the
doc string we learn that the value (returned, presumably) is a list
(HEIGHT VPOS YPOS OFFBOT). That's contradictory. If the height in
pixels is returned, that is presumably an integer, not a list.
 
The Elisp manual repeats all of the confusion and other defects of the
doc string. In fact, it is almost verbatim the same text.
 

In GNU Emacs 23.0.94.1 (i386-mingw-nt5.1.2600)
 of 2009-05-24 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'