bug#29328: 24.5; doc string of `transpose-subr`

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

> >> > The doc string should describe each parameter.  Parameter SPECIAL is
> >> > not described, and its name is not specific or enlightening.
> >>
> >> I don't see how it can be meaningfully documented.
> >
> > That's tantamount to saying that the parameter has no meaning,
> > no behavior.  If it does something then that something should
> > be describable, in some way, at least.  The place to start is
> > with the intention - why do we have such a parameter?  What
> > does it let you do?  Why/when would code ever make use of it?
> 
> How about something like this:
> -forward-paragraph).  If ARG is zero, exchanges the current object
> +forward-paragraph).  If SPECIAL is non-nil, then MOVER should
> +return the bounds of the object as a cons (BEG . END) instead.
> +If ARG is zero, exchanges the current object
>  with the one containing mark.  If ARG is an integer, moves the
>  current object past ARG following (if ARG is positive) or
>  preceding (if ARG is negative) objects, leaving point after the

If that's the behavior, fine with me.  I don't know
what the behavior is.

But the parameters should be described in order,
i.e., ARGS should be described before SPECIAL.