GNU bug report logs - #29328
24.5; doc string of `transpose-subr`

Previous Next

Full log

Message #20 received at 29328 <at> debbugs.gnu.org (full text, mbox):

From: Noam Postavsky <npostavs <at> users.sourceforge.net>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 29328 <at> debbugs.gnu.org
Subject: Re: 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 <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.