bug#24860: 24.5; doc string of `transpose-sexps'

[Drew Adams]

1. This part of the doc string is unclear.  I have no idea what it is
really trying to say.

  Does not work on a sexp that point is in the middle of
  if it is a list or string.

What does "does not work" mean?  Raises an error?  Does something that
we cannot describe?  Does nothing?

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 |.  What
"does not work" in that case, with an ARG of 1?

This part of the doc is completely unclear.  What's more, it is not
mentioned in the Emacs manual (node `Expressions').

2. The doc string needs to say, as does the manual (node `Expressions'),
that a zero ARG has particular behavior (and describe it) - it is not a
no-op.

3. I think it would help for the manual (node `Expressions') to give a
simple example showing the usefulness of the zero ARG case.  It's not
too clear from the description why this behavior is provided.


In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'