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

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

> > If that's what is meant then that's what the doc should say:
> > "the innermost sexp containing point".
> 
> I think that's unnecessary if this is a "reasonable interpretation",
> i.e. it's common sense, so making it explicit tends to be pedantic.
> Do you really think this is not the common sense way of understanding
> it? If so, I guess you have a function in mind that behaves differently;
> which one?

When you know what the code does it is very easy to think
that vague doc is "reasonable" enough and "common sense".
Readers of the doc should not need to depend on what you
might understand of the code.

It is not unreasonable to be clear and brief.  I repeat:
if the doc means "the innermost sexp containing point" then
it should just say that.  That's not being pedantic; it's
being clear.

I stand by the bug #24860 report.  Saying that something
described vaguely "does not work" is not helpful enough.

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

There is no way for users to know what that really means
(except by checking the code).