[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#29328: 24.5; doc string of `transpose-subr`
From: |
Noam Postavsky |
Subject: |
bug#29328: 24.5; doc string of `transpose-subr` |
Date: |
Fri, 17 Nov 2017 10:23:24 -0500 |
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