On Wed, 4 Dec 2019 19:04:10 +0100
martin rudalics wrote:

>> You will see that functions which use the likes of default-font-height
>> are interested in the selected window on the selected frame.
>
> But in that case the first line of the doc-string of
> 'default-font-height'
>
>   Return the height in pixels of the current buffer's default face font.
>
> is totally misleading because, as you noted above, asking for such a
> value is meaningless when the current buffer is not displayed in the
> selected window.  Please try to fix these doc-strings so they tell
> what the functions actually do and not how they are used.

Indeed, FWIW I've been bitten by this recently, too, and have been
meaning to submit the patch attached, although now seeing this
discussion, more clarification (and from a more knowledgeable person)
might be needed. I simply corrected what seemed to be obvious errors,
but maybe it can at least serve as another evidence of the confusion.

-- 
Štěpán