GNU bug report logs - #31574
27.0; Doc string for `with-help-window'

Previous Next

Full log

View this message in rfc822 format

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 31574 <at> debbugs.gnu.org
Subject: bug#31574: 27.0; Doc string for `with-help-window'
Date: Thu, 24 May 2018 11:26:22 -0700 (PDT)

> I told yesterday in response to another message of yours how can you
> see the changes in the repository using  Web browser.  Please take a
> look, then we can discuss the fix.

I looked at your mention of this, which was apparently in a bug
#31311 message.  After jumping through some hoops, yes, one can
see the texinfo source code.

But even trying that for this bug, I don't see it.  I don't see
anything about 31574 here, which is presumably the latest and
right place to look for it (?):

http://git.savannah.gnu.org/cgit/emacs.git/log/

> > The real problem is that after you follow the link there
> > is NOTHING about `with-help-window', AFAICT.
> 
> No, the real problem is that the reference to help-window-setup gave
> you wrong expectations regarding what information that function should
> add.  My change tried to make those expectations match the original
> intent.

Which was what?

> > And I should have been clear that the doc string of
> > `help-window-setup' is even more problematic.  It doesn't
> > say anything helpful at all, AFAICT.
> 
> That's a subroutine, so I don't necessarily see its doc string as
> something we need to invest an effort in.

We disagree.  A doc string that says only that WINDOW is the
windo for displaying the help buffer (obvious), plus just
"Return VALUE" might as well not even exist (and the optional
arg should be called RETURN-VALUE).

This is a non-trivial function.  Some explanation of what the
window "setup" entails is appropriate.

Previous Next

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