[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#28947: 26.0; doc string of `window-normalize-buffer' and similar
From: |
martin rudalics |
Subject: |
bug#28947: 26.0; doc string of `window-normalize-buffer' and similar |
Date: |
Mon, 23 Oct 2017 10:06:01 +0200 |
> The doc string does not tell anything more than what the doc of
> `get-buffer' tells you. In fact, it tells you less.
>
> Why does the function name start with `window-'? Is it just because it
> is in file window.el? If so, consider moving it. If the function has
> some relation to a window (I don't see anything in the code that
> indicates that) then please describe that in the doc string.
>
> It looks like this should be called something like `get-live-buffer',
> and the doc string should say that if no live buffer can be found then
> an error is raised.
>
> The doc string should also say explicitly that if the arg is nil then
> the current buffer is returned.
I rewrote the doc-string as follows:
Return buffer specified by BUFFER-OR-NAME.
BUFFER-OR-NAME must be a live buffer, a string naming a live
buffer or nil which means to return the current buffer.
This function is commonly used to process the (usually optional)
"BUFFER-OR-NAME" argument of window related functions where nil
stands for the current buffer.
> Actually, if the arg is a buffer name that names a dead buffer then that
> dead buffer is returned, so that wouldn't exactly be reflected in the
> name `get-live-buffer'.
>
> I wonder why that behavior. Should the 3rd cond branch perhaps check
> that the result is a live buffer (in effect using the 2nd cond branch on
> the buffer gotten)?
Right. This should have been fixed in the release version.
> Similar remarks apply to function `window-normalize-frame'. Not
> specific to a window. Mention that a nil arg returns selected frame.
Done.
> And similar remarks apply to function `window-normalize-window'.
> In this case the function is about windows, but the suffix `-window' is
> enough. No need for prefix `window-'.
These three functions did not have the `window-' prefix initially. The
prefix was requested by a maintainer and added later.
Thanks for the report, martin