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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 29328 in the body.
You can then email your comments to 29328 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.5; doc string of `transpose-subr`
Date: Thu, 16 Nov 2017 14:41:40 -0800 (PST)

The doc string should describe each parameter.  Parameter SPECIAL is not
described, and its name is not specific or enlightening.

See http://lists.gnu.org/archive/html/help-gnu-emacs/2017-11/msg00190.html



In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 29328 <at> debbugs.gnu.org
Subject: Re: bug#29328: 24.5; doc string of `transpose-subr`
Date: Fri, 17 Nov 2017 15:46:49 +0200

> Date: Thu, 16 Nov 2017 14:41:40 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> 
> The doc string should describe each parameter.  Parameter SPECIAL is not
> described, and its name is not specific or enlightening.
> 
> See http://lists.gnu.org/archive/html/help-gnu-emacs/2017-11/msg00190.html

I don't see how it can be meaningfully documented.

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

From: Robert Pluim <rpluim <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Drew Adams <drew.adams <at> oracle.com>, 29328 <at> debbugs.gnu.org
Subject: Re: bug#29328: 24.5; doc string of `transpose-subr`
Date: Fri, 17 Nov 2017 15:25:43 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Date: Thu, 16 Nov 2017 14:41:40 -0800 (PST)
>> From: Drew Adams <drew.adams <at> oracle.com>
>> 
>> The doc string should describe each parameter.  Parameter SPECIAL is not
>> described, and its name is not specific or enlightening.
>> 
>> See http://lists.gnu.org/archive/html/help-gnu-emacs/2017-11/msg00190.html
>
> I don't see how it can be meaningfully documented.

It's also only used by transpose-sexps. Perhaps rename the parameter
to something like non-standard-calling-convention, even though that's
far too long?

Robert

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Robert Pluim <rpluim <at> gmail.com>
Cc: drew.adams <at> oracle.com, 29328 <at> debbugs.gnu.org
Subject: Re: bug#29328: 24.5; doc string of `transpose-subr`
Date: Fri, 17 Nov 2017 16:57:00 +0200

> From: Robert Pluim <rpluim <at> gmail.com>
> Cc: Drew Adams <drew.adams <at> oracle.com>,  29328 <at> debbugs.gnu.org
> Date: Fri, 17 Nov 2017 15:25:43 +0100
> 
> >> See http://lists.gnu.org/archive/html/help-gnu-emacs/2017-11/msg00190.html
> >
> > I don't see how it can be meaningfully documented.
> 
> It's also only used by transpose-sexps. Perhaps rename the parameter
> to something like non-standard-calling-convention, even though that's
> far too long?

Not only is it too long, it is equally non-specific.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 29328 <at> debbugs.gnu.org
Subject: RE: bug#29328: 24.5; doc string of `transpose-subr`
Date: Fri, 17 Nov 2017 07:02:22 -0800 (PST)

> > 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?

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Noam Postavsky <npostavs <at> users.sourceforge.net>
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 07:36:28 -0800 (PST)

> >> > 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.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 29328-done <at> debbugs.gnu.org
Subject: Re: bug#29328: 24.5; doc string of `transpose-subr`
Date: Fri, 17 Nov 2017 17:45:30 +0200

> Date: Fri, 17 Nov 2017 07:02:22 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 29328 <at> debbugs.gnu.org
> 
> > > 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.

No, it isn't.  It's tantamount to saying what I have just said.

> 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?

Thanks for the lecture.  Rest assured, I asked myself all of those
questions, and then some.  This is an internal subroutine, so it
doesn't have to document everything.

Please accept my judgment on this.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Noam Postavsky <npostavs <at> users.sourceforge.net>
Cc: drew.adams <at> oracle.com, 29328 <at> debbugs.gnu.org
Subject: Re: bug#29328: 24.5; doc string of `transpose-subr`
Date: Fri, 17 Nov 2017 17:47:51 +0200

> From: Noam Postavsky <npostavs <at> users.sourceforge.net>
> Date: Fri, 17 Nov 2017 10:23:24 -0500
> Cc: Eli Zaretskii <eliz <at> gnu.org>, 29328 <at> debbugs.gnu.org
> 
>    "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.

It's the other way around: SPECIAL doesn't require MOVER to do
anything, it's an INDICATION that MOVER does something "special".

Please just drop this.  It's another bikeshedding argument.  We don't
need to document this.

Previous Next

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