GNU bug report logs - #14843
24.3.50; `line-move', `line-move-visual' need doc strings

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 14843 in the body.
You can then email your comments to 14843 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.3.50; `line-move', `line-move-visual' need doc strings
Date: Thu, 11 Jul 2013 08:40:49 -0700 (PDT)

These functions, especially `line-move', are used all over the place.
They need doc strings, with complete descriptions of their parameters.

In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-07-01 on LEG570
Bzr revision: 113246 lekktu <at> gmail.com-20130701165437-ea20s94hqwp3ttaj
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --enable-checking CFLAGS='-O0 -g3'
 CPPFLAGS='-DGLYPH_DEBUG=1 -I/c/usr/include''

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 14843 <at> debbugs.gnu.org
Subject: Re: bug#14843: 24.3.50;
 `line-move', `line-move-visual' need doc strings
Date: Thu, 11 Jul 2013 21:32:41 +0300

> Date: Thu, 11 Jul 2013 08:40:49 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> 
> These functions, especially `line-move', are used all over the place.
> They need doc strings, with complete descriptions of their parameters.

They are internal functions.  Under what circumstances did you need to
use them directly?  Why wasn't next/previous-line enough?

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 14843 <at> debbugs.gnu.org
Subject: RE: bug#14843: 24.3.50; `line-move', `line-move-visual' need doc
 strings
Date: Thu, 11 Jul 2013 11:50:06 -0700 (PDT)

> > These functions, especially `line-move', are used all over the place.
> > They need doc strings, with complete descriptions of their parameters.
> 
> They are internal functions.  Under what circumstances did you need to
> use them directly?  Why wasn't next/previous-line enough?

Read what I wrote: they "are used all over the place".  In the Emacs code
alone, not to mention in 3rd-party code.  They are not "internal" to
simple.el.  They are not internal to anything.  Reality.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 14843 <at> debbugs.gnu.org
Subject: Re: bug#14843: 24.3.50;
 `line-move', `line-move-visual' need doc strings
Date: Thu, 11 Jul 2013 22:06:41 +0300

> Date: Thu, 11 Jul 2013 11:50:06 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 14843 <at> debbugs.gnu.org
> 
> > > These functions, especially `line-move', are used all over the place.
> > > They need doc strings, with complete descriptions of their parameters.
> > 
> > They are internal functions.  Under what circumstances did you need to
> > use them directly?  Why wasn't next/previous-line enough?
> 
> Read what I wrote: they "are used all over the place".  In the Emacs code
> alone, not to mention in 3rd-party code.  They are not "internal" to
> simple.el.  They are not internal to anything.  Reality.

That an internal function is used all over the Emacs code is a small
wonder.  It just means someone was smart enough to capture a frequent
need of many features.

As for 3rd-party code, if you have such code, or happen to know why
line-move was used instead of next/previous-line, please tell.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 14843 <at> debbugs.gnu.org
Subject: RE: bug#14843: 24.3.50; `line-move', `line-move-visual' need doc
 strings
Date: Thu, 11 Jul 2013 13:52:23 -0700 (PDT)

> > > > These functions, especially `line-move', are used all over the place.
> > > > They need doc strings, with complete descriptions of their parameters.
> > >
> > > They are internal functions.  Under what circumstances did you need to
> > > use them directly?  Why wasn't next/previous-line enough?
> >
> > Read what I wrote: they "are used all over the place".  In the Emacs code
> > alone, not to mention in 3rd-party code.  They are not "internal" to
> > simple.el.  They are not internal to anything.  Reality.
> 
> That an internal function is used all over the Emacs code is a small
> wonder.  It just means someone was smart enough to capture a frequent
> need of many features.

And each person who wrote such Emacs code needed to figure out for herself
what the parameters mean (or not bother).

Perhaps it is also a small wonder that NONE of the uses of `line-move',
including those in simple.el itself, make ANY USE of the additional
parameters introduced in Emacs 22 (and not used even in 22).

An indication, perhaps, that even Emacs Dev could use a little Emacs
self-documenting.  Doc strings are for everyone.

Arguing not to create clear doc strings for "internal" functions made little
sense in the 1960s.  It makes no sense at all now.

In bygone days, Emacs code had comments instead of doc strings for some
functions (sometimes systematically, for a given library).  Most of those
comments were changed to doc strings once the Dark Ages were over.

Look at the large comments preceding these two function defuns.  Yet even
those elaborate comments do not describe the parameters.  Emacs can do
better.  Much better.

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

From: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 14843 <at> debbugs.gnu.org
Subject: Re: bug#14843: 24.3.50;
 `line-move', `line-move-visual' need doc strings
Date: Thu, 11 Jul 2013 19:04:15 -0400

> They need doc strings, with complete descriptions of their parameters.

Agreed.


        Stefan "Looking forward to your corresponding commit"

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 14843 <at> debbugs.gnu.org
Subject: Re: bug#14843: 24.3.50;
 `line-move', `line-move-visual' need doc strings
Date: Fri, 12 Jul 2013 09:54:02 +0300

> Date: Thu, 11 Jul 2013 13:52:23 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 14843 <at> debbugs.gnu.org
> 
> Perhaps it is also a small wonder that NONE of the uses of `line-move',
> including those in simple.el itself, make ANY USE of the additional
> parameters introduced in Emacs 22 (and not used even in 22).

That's not true.  These arguments are used by next-line and previous
line.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 14843 <at> debbugs.gnu.org
Subject: RE: bug#14843: 24.3.50; `line-move', `line-move-visual' need doc
 strings
Date: Fri, 12 Jul 2013 01:26:38 -0700 (PDT)

> > Perhaps it is also a small wonder that NONE of the uses of `line-move',
> > including those in simple.el itself, make ANY USE of the additional
> > parameters introduced in Emacs 22 (and not used even in 22).
> 
> That's not true.  These arguments are used by next-line and previous
> line.

Yes and no.  One of them is used; the other (TO-END) is not.

But you're missing the point.  Neither is used in any of the zillion uses
of `line-move' - other than `(next|previous)-line'.  And that lends some
support to the idea that those programming those uses might not have even
understood these undocumented parameters.

In addition, it is NOT the case that optional parameter TO-END is used
anywhere.  And I do mean strictly anywhere this time.  It was introduced
in Emacs 22 but NEVER used anywhere, AFAICT.  Again, not being documented
might be one reason this vestige (vestige of nothing) has never been
used and has never been removed.

I made this clear in bug #14844 (where I mentioned only TO-END, not also
TRY-VSCROLL).

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 14843 <at> debbugs.gnu.org
Subject: Re: bug#14843: 24.3.50;
 `line-move', `line-move-visual' need doc strings
Date: Fri, 12 Jul 2013 12:19:12 +0300

> Date: Fri, 12 Jul 2013 01:26:38 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 14843 <at> debbugs.gnu.org
> 
> > > Perhaps it is also a small wonder that NONE of the uses of `line-move',
> > > including those in simple.el itself, make ANY USE of the additional
> > > parameters introduced in Emacs 22 (and not used even in 22).
> > 
> > That's not true.  These arguments are used by next-line and previous
> > line.
> 
> Yes and no.  One of them is used; the other (TO-END) is not.

It is documented to be unused.

> But you're missing the point.  Neither is used in any of the zillion uses
> of `line-move' - other than `(next|previous)-line'.  And that lends some
> support to the idea that those programming those uses might not have even
> understood these undocumented parameters.

The arguments to next/previous-line are all documented now.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
Cc: 14843 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#14843: 24.3.50;
 `line-move', `line-move-visual' need doc strings
Date: Fri, 07 Feb 2014 22:28:34 -0800

Stefan Monnier <monnier <at> IRO.UMontreal.CA> writes:

>> They need doc strings, with complete descriptions of their parameters.
>
> Agreed.

Fixed on trunk.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Previous Next

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