bug#18112: 24.4.50; emacs --daemon infinite loop in find_interval

[Eli Zaretskii]

> Date: Fri, 08 Aug 2014 12:10:02 +0200
> From: martin rudalics <rudalics@gmx.at>
> CC: 18112@debbugs.gnu.org, mvoteiza@udel.edu
> 
>  > As long as I have your attention: how about adding some comments
>  > and/or text to respective doc strings to explain what exactly the
>  > following functions do, and why/when are they needed?
>  >
>  >    window-normal-size
>  >    window-new-total
>  >    window-new-normal
>  >    window-new-pixel
>  >
>  > and the corresponding set-* functions.  Their doc strings are just
>  > tautological repetition of their names, which isn't helpful.  And the
>  > ELisp manual doesn't say a word about them, so the doc strings need to
>  > do a better job, IMO.
> 
> I've tried to do that now.  Please have a look.

Thanks.  This is an improvement for the functions that deal with the
"normal" size (which should have been called "normalized", but I guess
that's water under the bridge now).

I see no improvement for the "total" size.  The additions to the doc
strings point to window-total-size, but that function's doc string
does not explain what is the semantics of "total" in this respect.
(The doc string of window-total-size references window-total-width and
window-total-height, which do say something about that, but having to
traverse more than 1 hyperlink to find the information is not a good
idea, IMO.)

Also, the way you document the *-new-* functions could be improved.
You say something like

  The new pixel size of WINDOW is used by `window-resize-apply' and, if
  that function succeeds, will be subsequently returned by the functions
  `window-pixel-height' and `window-pixel-width'.

I suggest instead to say something that describes the effect, but not
how the effect is achieved (which is low-level information that
obscures and obfuscates what the reader would like to know):

  The new pixel size of WINDOW, if it is valid, will be shortly
  installed as WINDOW's size.

Thanks.