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

[Noam Postavsky <npostavs@users.sourceforge.net>]

On Fri, Nov 17, 2017 at 10:02 AM, Drew Adams <drew.adams@oracle.com> wrote:
>> > 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:

--- i/lisp/simple.el
+++ w/lisp/simple.el
@@ -6951,7 +6951,9 @@ transpose-subr
   "Subroutine to do the work of transposing objects.
 Works for lines, sentences, paragraphs, etc.  MOVER is a function that
 moves forward by units of the given object (e.g. forward-sentence,
-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