bug#34749: 26.1; `delete-windows-on': (1) doc, (2) bug, (3) bug, (4) candidates

[Drew Adams]

There are several things wrong with `delete-windows-on', and several things 
that call for improvement.


1. The doc string should first of all completely describe the
interactive behavior and only secondarily describe the Lisp behavior
(completely).

In particular, this doc string should say explicitly what happens with a
prefix arg, including what happens with different kinds of raw prefix
arg (including, but not limited to, 0).

The doc string should also say that a prefix arg is ignored when the
condition of the last paragraph applies (dedicated window alone in
frame, with other frames existing), if that's true.

In general: Please fix the doc string to provide a correct and complete
description of the interactive behavior.


2. The doc string says that when FRAME is anything other than t,
`visible', 0, or a frame then all windows showing the buffer on any
frame are deleted.  But that's not the case:

emacs -Q

`C-h f delete-windows-on'

With window *Help* selected: `C-x 5 2', to display it also in another
frame.

With window *Help* in the original frame selected:
`C-u M-x delete-windows-on *Help*'

Only the *Help* window on the selected frame is deleted, not the one on
the separate frame.  But the doc says that FRAME, which is `(4)' should
cause all windows showing buffer *Help* to be deleted from all frames.

It seems like the interactive behavior is not correct, as well as being
poorly documented.  It's hard to know just what behavior was intended,
or what behavior would be best if (as it seems) we still need to design
this.


3. Why is `B' used in the interactive spec instead of `b'?  What's the
use case for deleting windows showing a nonexistent buffer?


4. The buffer candidates available for completion (which should also be
the only buffer names available for entry - see #3) should depend on
which frames are used, i.e., on the prefix arg or its absence.

You should be presented only with the names of buffers that are actually
shown in windows on the frames that you've chosen to consider for
window-deletion.

In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 10.0.17134
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''