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

[Drew Adams <drew.adams@oracle.com>]

This is the `eshell' doc string:

 Create an interactive Eshell buffer.
 The buffer used for Eshell sessions is determined by the value of
 'eshell-buffer-name'.  If there is already an Eshell session active in
 that buffer, Emacs will simply switch to it.  Otherwise, a new session
 will begin.  A numeric prefix arg (as in 'C-u 42 M-x eshell RET')
 switches to the session with that number, creating it if necessary.  A
 nonnumeric prefix arg means to create a new session.  Returns the
 buffer selected (or created).

That's a wall of text.  But the problem to report here is that the
_number_ of a session is unclear.  What is it and, especially, what, if
anything, does it have to do with `eshell-buffer-name'.

Experimenting a bit, a guess is that the names of Eshell buffers use
`eshell-buffer-name' followed, by all but the first, by "<N>", where N =
2,3,4... as additional sessions are created.  And with a numeric prefix
arg M, `eshell' tries to find a session with buffer name ending in <M>.

E.g., I tried `M-x eshell' followed by `C-u M-x eshell'.  The first
created buffer `*eshell*', and the second created buffer `*eshell<2>*'
(not `*eshell<4>*', BTW).

This naming convention should be described in the doc string, in order
to make clear (1) how `eshell-buffer-name' is used as a "base name" and
(2) how the prefix arg relates to the buffer-name convention.

Also, the doc string for variable `eshell-buffer-name' is poor.  That's
really where the use of the value as a "base name" needs to be described
(i.e., make clear what is mean by "base name" and how multiple eshell
buffers are named).


In GNU Emacs 26.2 (build 1, x86_64-w64-mingw32)
 of 2019-04-13
Repository revision: fd1b34bfba8f3f6298df47c8e10b61530426f749
Windowing system distributor `Microsoft Corp.', version 10.0.17763
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''