bug#17007: 24.3.50; describe-key/function evaluates documentation function in the wrong buffer

[martin rudalics]

> It's simpler if I give you an emacs -Q recipe, right? In your *scratch*
> buffer:
>
>     (defun foo ())
>     (defun foo-doc ()
>       (format "Foo does nothing, and by the way your tab does `%s'"
>                         (key-binding "\t")))
>     (put 'foo 'function-documentation '(foo-doc))
>     (describe-function 'foo)
>
> This fails on the latest Emacs, i.e. the last line returned by the last
> form is
>
>     "Foo does nothing, and by the way your tab does `forward-button'"
>
> Whereas it should report, as in Emacs 24.3
>
>     "Foo does nothing, and by the way your tab does `indent-for-tab-command'"

Confirmed.

> The trace of functions is the following:
>
> 1 -> (describe-function foo)
> | 2 -> (describe-function-1 foo)
> | | 3 -> (documentation foo t)
> | | 3 <- documentation: "Foo does nothing, and by the way your tab does 
`forward-button'"
> | 2 <- describe-function-1: nil
> 1 <- describe-function: "foo is a Lisp function.
>
> But that doesn't show how the macro `with-temp-buffer-window', expanded
> from `with-help-window', eventually wraps the latter's BODY in a
> `with-current-buffer' call, making its forms be evaluated in the newly
> created *Help* buffer, instead of *scratch*.

Indeed.

> One of those forms is the
> call to `describe-function-1', which eventually calls `foo-doc'.
>
> As I explained in my last email (which got sent from the wrong address
> but is here
> http://lists.gnu.org/archive/html/bug-gnu-emacs/2014-03/msg00411.html)
> it was the reversion of two lines in `with-temp-buffer-window' that
> broke it.

Not really.  The current version of `with-temp-buffer-window' and that
released with Emacs 24.3 are the same.  It changed only intermittently
and that's what you noticed.  Or can you spot a difference now?

>  But maybe it was fixing something else that I don't understand. Can
> you help me understand what you were achieving with the original fix
> and the reversion?

I first reacted to a bug report by Nicolas Richard

http://debbugs.gnu.org/cgi/bugreport.cgi?bug=16816

and tried to make it behave as in the doc-string.  Unfortunately, this
broke things as subsequently remarked by Juanma in the same thread and
also broke code Thierry wrote as reported in

http://debbugs.gnu.org/cgi/bugreport.cgi?bug=16882

so I decided to restore the 24.3 behavior.  I'm still not fine with that
but it's now some time since 24.3 is out and I'm a bit reluctant to
change it back again, mostly so because I don't know how many bugs such
a change might produce and how soon they'd get detected.

And I'm still too silly to understand how this (apparently?) worked with
24.3 and why it's broken now.  Any ideas?

martin