quit-window

[martin rudalics <rudalics@gmx.at>]

The doc-string of `quit-window' says

(defun quit-window (&optional kill window)
   "Quit the current buffer.  Bury it, and maybe delete the selected frame.
\(The frame is deleted if it contains a dedicated window for the buffer.)
With a prefix argument, kill the buffer instead.

Noninteractively, if KILL is non-nil, then kill the current buffer,
otherwise bury it.

If WINDOW is non-nil, it specifies a window; we delete that window,
and the buffer that is killed or buried is the one in that window."

The following parts seem dubious:

- "Quit the current buffer."

   The function is called `quit-window' its doc-string says "quit the
   current buffer".  Since the current buffer is not necessarily the
   buffer displayed in the selected window this sentence is both
   misleading and wrong.

- "Bury it, and maybe delete the selected frame."

   KILL non-nil will kill the buffer, not bury it.  WINDOW non-nil will
   affect WINDOW's frame, not the selected frame.

- "\(The frame is deleted if it contains a dedicated window for the buffer.)"

   Only if there are no other windows on that frame.

- "Noninteractively, if KILL is non-nil, then kill the current buffer,
   otherwise bury it."

   "current buffer" and "bury" are misleading again.

Could someone with a good sense of what's going on in this function
improve that?  Also

       (and (or (window-minibuffer-p) (window-dedicated-p window))

should probably become

       (and (or (window-minibuffer-p window) (window-dedicated-p window))