quit-window

[martin rudalics]

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))