bug#30792: 26.0.91; improve docstring of with-help-window

[Nick Helm <nick@tenpoint.co.nz>]

On Thu, 15 Mar 2018 at 09:05:57 +1300, martin rudalics wrote:

>> which is why I think the modified doc string should keep the
>> part of the existing doc string which tells about this special setup.
>
> The comment before the definition of `with-help-window' says what it
> does additionally.  It think it's really not necessary to say it in
> the doc-string.

I don't think a user should have to read code comments to work out how
to use a macro. Besides, all of those comments (except (4)) appear in
the macro's manual entry, though not as clearly.

Isn't it sufficient that the docstring says it puts the buffer in
`help-mode'? If a user wants to find out what that means and how to
tweak the result, they can follow the link and read the help
documentation. If they're reading the docstring in the first place, they
almost certainly know how help works, and that pushing q quits a help
window by default.

> But if we change BUFFER-NAME to BUFFER-OR-NAME this should be
> reflected in the Elisp manual.

This was just a suggestion, as `with-help-window' simply passes the
value along to `with-temp-buffer-window'.

I think the expected use of `with-help-window' was to receive output
from `help-buffer', which returns an existing help buffer object or
"*Help*". But that's not the only way to use `with-help-window' and
`with-temp-buffer-window' can accept any existing buffer object or a
string name to create a new one. I think it would be useful if
`with-help-window' made that clear by using the same name.

Nick