bug#37178: 26.2; doc strings of `eshell' and `eshell-buffer-name'

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> Yes, thanks; much better.

Thanks for reviewing.

> But the problem I pointed out is still there.
>
> If you use a numeric prefix arg and a buffer with that number already exists, 
> then it is used.  No problem.
>
> But if you use a numeric prefix arg and no buffer with that number exists, 
> it's not true that a buffer with that number is created (as both the original 
> and your patch say).  As mentioned, I tried `C-u' (numerically 4) with one 
> existing buffer, but it created buffer <2>, not <4>.
>
> Instead, a new buffer is created with, as number, the successor of the 
> largest existing one.

Indeed.  It treats a plain prefix argument ('C-u') differently from a
numeric prefix argument ('C-u 42').

> Actually, even that might not be correct, if some existing buffers have been 
> deleted.  I don't have time now to check what happens in general - does it 
> pick the successor of the largest existing number? does it pick the first 
> number after an existing one before a hole, i.e., starting to fill in the 
> hole?
>
> E.g., if there are buffers <2>, <3>, and <7>, does it pick <8>? does it pick 
> <4>?

It picks <4> in this case, which I think makes sense.  But I don't
think the doc string needs to go into that level of detail, since that
part of the behaviour is less important than the use cases:

1. Create a new Eshell session, or pop to an existing. (M-x eshell)
2. Create a new Eshell session (C-u M-x eshell)
3. Visit given Eshell session (C-u 2 M-x eshell)

All of that is actually already documented in the suggested doc string:

    Start a new Eshell session, or switch to an already active
    session.  Return the buffer selected (or created).

    With a numeric prefix arg (as in `C-u 42 M-x eshell RET'), switch
    to the session with that number, or create it if it doesn't
    exist.  A nonnumeric prefix arg means to create a new session.

Maybe it could be made more clear, but I don't see how if we also want
to keep it sufficiently succinct.

Best regards,
Stefan Kangas