bug#32798: 26; doc string of `pop-to-buffer-same-window' and similar

[Drew Adams]

The doc string of `pop-to-buffer-same-window' doesn't describe the

behavior well enough.  Similar problems exist with other doc strings

that now, in essence, just send you down the rabbit holes of

`display-buffer' and `display-buffer-alist'.

 

Contrast the doc string of `switch-to-buffer', for which `p-t-b-s-w' is

often (rightfully) promoted as a replacement.  There you see a

description of the behavior for a dedicated window, for example:

 

  If the selected window is dedicated (‘window-dedicated-p’), then use

  another window, regardless of argument FORCE-SAME-WINDOW.

 

Clear, simple.  What does `p-t-b-s-w' do if the selected window is

dedicated? Let's find out...

 

Unfortunately, ever since `display-buffer-alist' came along it seems

that the doc of specific functions pretty much just punt, forcing you

to follow a long and winding search thread to learn their actual

behavior.

 

For `p-t-b-s-w', for example, if you want to find out the particulars

then you need to do something like this:

 

1. You try `C-h f pop-to-buffer-same-window'. It says only "in some

window, preferably the same one".  (Preferably how?  What if the

window is dedicated?)

 

2. You go to the `p-t-b-s-w' source code, which you see is just this:

 

  (pop-to-buffer buffer display-buffer--same-window-action norecord)

 

Great; very simple code.  What does it mean?

 

3. You use `C-h v display-buffer--same-window-action' (an "internal"

variable?) to find ... essentially no new info - an "action for

displaying in the same window".  A wasted detour, but the only thing

that was specific in that invocation of `pop-to-buffer'.

 

4. So you try `C-h f pop-to-buffer' (or click the link from the

`p-t-b-s-w' doc), where you find only a reference to `display-buffer'

and mention of its ACTION argument.  Hm, what's this?

 

5. You use `C-h f display-buffer' (or click the link from the `p-t-b'

doc) ... and you spend a day or two trying to make some sense of

the description of parameter ACTION.  Only half-kidding.

 

6. In spite of your time spent with the `d-b' doc, you still don't know

what the `p-t-b-s-w' behavior is.  So maybe you go back and look at `C-h

v display-buffer--same-window-action' again - and this time you look

closer at the value, not the doc:

 

  (display-buffer-same-window (inhibit-same-window))

 

You make an effort to realize that this list doesn't represent code that

invokes function `d-b-s-w' with argument `(i-s-w)'.  It's instead just

an alist whose car happens to be a function name.  (But perhaps you

mistakenly take another wasted detour here with `C-h f d-b-s-w'.)

 

7. Anyway, you now have the `display-buffer' ACTION alist, so you go

back to `C-h f display-buffer' to try some more to figure out the

behavior.

 

Deciphering the `d-b' doc, you now see that FUNCTION in this case is

`d-b-s-w', and the ALIST is `((inhibit-same-window))'.  You instantiate

the description to understand that `d-b-s-w' gets invoked with "two

arguments: the buffer to display" and the alist

`((inhibit-same-window))'.

 

Finally you feel you almost have it - you must be getting very close to

a description of `p-b-s-w'.  What `pop-to-buffer-same-window' does is

invoke `display-buffer-same-window', passing it the buffer to display

and `((inhibit-same-window))'.

 

8. So now you try `C-f display-buffer-same-window'.  There you see that

the buffer is displayed in the same window unless `inhibit-same-window'

has a nil value in the ALIST entry (not the case here), or the window is

a minibuffer, or it is dedicated to another buffer.

 

BRAVO!  You've finally found out what `pop-to-buffer-same-window' does

if the window is dedicated.  Well, almost - it would have been better

if, like the doc of `switch-to-buffer', there was a mention of

`window-dedicated-p' (with a link) - which tells you just what it means

for a window to be dedicated.

 

Could the doc for `p-t-b-s-w' have referred directly to `d-b-s-w"? Better

yet, could it have described that display behavior (and perhaps

mentioned `d-b-s-w')? You betcha.

 

Moral:

Doc of `switch-to-buffer': simple and clear.

Doc of  `pop-to-buffer-same-window': not so much.

 

Doc of specific functions should be specific.  The goal is not maximum

factorization - sending all doc strings down the rabbit hole of

`display-buffer'.

 

A user should get a fairly complete description for each function s?he

checks with `C-h f'.  Extreme factoring might sometimes be OK for the

Elisp manual - there it can make sense to guide readers toward

`display-buffer'.  But a doc string should not force you to follow a

long and winding path through the forest.  It should invite you to

explorer further with links - sure, but you should not have to follow

multiple links just to find out what the function you asked about does.

 

---

 

[BTW: The `d-b-s-w' doc says "has a non-nil `inhibit-same-window'

entry", which is not clear/correct.  It should say something like "has

an `inhibit-same-window' entry whose cdr is non-nil.  Alist entry

`(inhibit-same-window)' is a cons - it is not nil, but it is presumably

not what was intended by "a non-nil `i-s-w' entry".]

 

[BTW2: The `d-b' doc is wrong in saying, on the one hand, that FUNCTION

is either a function or a list of functions, and on the other hand,

"Each such FUNCTION...".  That should presumably be "Each such

function".  Otherwise, if FUNCTION is, say, `(foo bar toto)' then it

means "Each `(foo bar toto)'..." instead of each of `foo', `bar', and

`toto'...".  The latter is presumably what was intended.]

 

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.16299

Configured using:

`configure --without-dbus --host=x86_64-w64-mingw32

--without-compress-install 'CFLAGS=-O2 -static -g3''