GNU bug report logs - #18112
24.4.50; emacs --daemon infinite loop in find_interval

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: martin rudalics <rudalics <at> gmx.at>
Cc: mvoteiza <at> udel.edu, 18112 <at> debbugs.gnu.org
Subject: bug#18112: 24.4.50; emacs --daemon infinite loop in find_interval
Date: Fri, 08 Aug 2014 13:40:30 +0300

> Date: Fri, 08 Aug 2014 12:10:02 +0200
> From: martin rudalics <rudalics <at> gmx.at>
> CC: 18112 <at> debbugs.gnu.org, mvoteiza <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.