all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#29328: 24.5; doc string of `transpose-subr`
@ 2017-11-16 22:41 Drew Adams
  2017-11-17 13:46 ` Eli Zaretskii
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2017-11-16 22:41 UTC (permalink / raw)
  To: 29328

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'





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#29328: 24.5; doc string of `transpose-subr`
  2017-11-16 22:41 bug#29328: 24.5; doc string of `transpose-subr` Drew Adams
@ 2017-11-17 13:46 ` Eli Zaretskii
  2017-11-17 14:25   ` Robert Pluim
  2017-11-17 15:02   ` Drew Adams
  0 siblings, 2 replies; 9+ messages in thread
From: Eli Zaretskii @ 2017-11-17 13:46 UTC (permalink / raw)
  To: Drew Adams; +Cc: 29328

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#29328: 24.5; doc string of `transpose-subr`
  2017-11-17 13:46 ` Eli Zaretskii
@ 2017-11-17 14:25   ` Robert Pluim
  2017-11-17 14:57     ` Eli Zaretskii
  2017-11-17 15:02   ` Drew Adams
  1 sibling, 1 reply; 9+ messages in thread
From: Robert Pluim @ 2017-11-17 14:25 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 29328

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#29328: 24.5; doc string of `transpose-subr`
  2017-11-17 14:25   ` Robert Pluim
@ 2017-11-17 14:57     ` Eli Zaretskii
  0 siblings, 0 replies; 9+ messages in thread
From: Eli Zaretskii @ 2017-11-17 14:57 UTC (permalink / raw)
  To: Robert Pluim; +Cc: 29328

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#29328: 24.5; doc string of `transpose-subr`
  2017-11-17 13:46 ` Eli Zaretskii
  2017-11-17 14:25   ` Robert Pluim
@ 2017-11-17 15:02   ` Drew Adams
  2017-11-17 15:23     ` Noam Postavsky
  2017-11-17 15:45     ` Eli Zaretskii
  1 sibling, 2 replies; 9+ messages in thread
From: Drew Adams @ 2017-11-17 15:02 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 29328

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#29328: 24.5; doc string of `transpose-subr`
  2017-11-17 15:02   ` Drew Adams
@ 2017-11-17 15:23     ` Noam Postavsky
  2017-11-17 15:36       ` Drew Adams
  2017-11-17 15:47       ` Eli Zaretskii
  2017-11-17 15:45     ` Eli Zaretskii
  1 sibling, 2 replies; 9+ messages in thread
From: Noam Postavsky @ 2017-11-17 15:23 UTC (permalink / raw)
  To: Drew Adams; +Cc: 29328

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#29328: 24.5; doc string of `transpose-subr`
  2017-11-17 15:23     ` Noam Postavsky
@ 2017-11-17 15:36       ` Drew Adams
  2017-11-17 15:47       ` Eli Zaretskii
  1 sibling, 0 replies; 9+ messages in thread
From: Drew Adams @ 2017-11-17 15:36 UTC (permalink / raw)
  To: Noam Postavsky; +Cc: 29328

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#29328: 24.5; doc string of `transpose-subr`
  2017-11-17 15:02   ` Drew Adams
  2017-11-17 15:23     ` Noam Postavsky
@ 2017-11-17 15:45     ` Eli Zaretskii
  1 sibling, 0 replies; 9+ messages in thread
From: Eli Zaretskii @ 2017-11-17 15:45 UTC (permalink / raw)
  To: Drew Adams; +Cc: 29328-done

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#29328: 24.5; doc string of `transpose-subr`
  2017-11-17 15:23     ` Noam Postavsky
  2017-11-17 15:36       ` Drew Adams
@ 2017-11-17 15:47       ` Eli Zaretskii
  1 sibling, 0 replies; 9+ messages in thread
From: Eli Zaretskii @ 2017-11-17 15:47 UTC (permalink / raw)
  To: Noam Postavsky; +Cc: 29328

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2017-11-17 15:47 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2017-11-16 22:41 bug#29328: 24.5; doc string of `transpose-subr` Drew Adams
2017-11-17 13:46 ` Eli Zaretskii
2017-11-17 14:25   ` Robert Pluim
2017-11-17 14:57     ` Eli Zaretskii
2017-11-17 15:02   ` Drew Adams
2017-11-17 15:23     ` Noam Postavsky
2017-11-17 15:36       ` Drew Adams
2017-11-17 15:47       ` Eli Zaretskii
2017-11-17 15:45     ` Eli Zaretskii

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.