RE: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps'

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

> > +Unlike `transpose-words', point must be between the two sexps and not 
>   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > +in the middle of a sexp to be transposed.
>   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 
> The underlined sentence is not accurate, since transpose-sexps does
> work like transpose-words if point is in the middle of a symbol or
> number.  Here's a more accurate statement: "If point is in the middle
> of a list or string, you cannot transpose that sexp with another sexp."

See bug #24860 (https://debbugs.gnu.org/cgi/bugreport.cgi?bug=24860).

That bug points out that the doc statement is incorrect/incomplete.
But your statement is also incorrect/incomplete, IMO.

The problem is that "in the middle of a sexp" can mean different
things.  Which sexp?  In (foo "ab|c" 42), with point at |, is point
in the middle of a string sexp?  Yes.  Is it in the middle of a list
sexp?  Yes.  Is it between sexps `foo' and `42'?  Yes.

What does it mean to be in the middle of a list, for example?
A case mentioned in the bug report is this:

>> When point is in the middle of a list it can also be between two
>> sexps, which themselves could be lists: ((foo)|(bar)), with point at |.

Point here is in the middle of the outer list, but it is between the
two inner lists.  Any text description needs to be more careful and
explicit, if it really wants to make the point clear.

Bug #24860 mentions a few different problems with the doc string.
Some of them were addressed; others apparently not.