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

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

[Drew Adams]

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'

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

[Eli Zaretskii]

> Date: Thu, 16 Nov 2017 14:41:40 -0800 (PST)
> From: 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.
> 
> See http://lists.gnu.org/archive/html/help-gnu-emacs/2017-11/msg00190.html

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

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

[Robert Pluim]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Thu, 16 Nov 2017 14:41:40 -0800 (PST)
>> From: 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.
>> 
>> 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

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

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: Drew Adams <drew.adams@oracle.com>,  29328@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.

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

[Drew Adams]

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

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

[Noam Postavsky]

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

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

[Drew Adams]

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

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

[Eli Zaretskii]

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

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

[Eli Zaretskii]

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