* bug#14843: 24.3.50; `line-move', `line-move-visual' need doc strings [not found] ` <<83r4f46hmm.fsf@gnu.org> @ 2013-07-11 20:52 ` Drew Adams 2013-07-12 6:54 ` Eli Zaretskii 0 siblings, 1 reply; 10+ messages in thread From: Drew Adams @ 2013-07-11 20:52 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 14843 > > > > 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#14843: 24.3.50; `line-move', `line-move-visual' need doc strings 2013-07-11 20:52 ` bug#14843: 24.3.50; `line-move', `line-move-visual' need doc strings Drew Adams @ 2013-07-12 6:54 ` Eli Zaretskii 0 siblings, 0 replies; 10+ messages in thread From: Eli Zaretskii @ 2013-07-12 6:54 UTC (permalink / raw) To: Drew Adams; +Cc: 14843 > Date: Thu, 11 Jul 2013 13:52:23 -0700 (PDT) > From: Drew Adams <drew.adams@oracle.com> > Cc: 14843@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. ^ permalink raw reply [flat|nested] 10+ messages in thread
[parent not found: <<83e00f63-4458-4901-8816-4875f599d9cc@default>]
[parent not found: <<83li5c5kvp.fsf@gnu.org>]
* bug#14843: 24.3.50; `line-move', `line-move-visual' need doc strings [not found] ` <<83li5c5kvp.fsf@gnu.org> @ 2013-07-12 8:26 ` Drew Adams 2013-07-12 9:19 ` Eli Zaretskii 0 siblings, 1 reply; 10+ messages in thread From: Drew Adams @ 2013-07-12 8:26 UTC (permalink / raw) To: Eli Zaretskii, Drew Adams; +Cc: 14843 > > 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). ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#14843: 24.3.50; `line-move', `line-move-visual' need doc strings 2013-07-12 8:26 ` Drew Adams @ 2013-07-12 9:19 ` Eli Zaretskii 0 siblings, 0 replies; 10+ messages in thread From: Eli Zaretskii @ 2013-07-12 9:19 UTC (permalink / raw) To: Drew Adams; +Cc: 14843 > Date: Fri, 12 Jul 2013 01:26:38 -0700 (PDT) > From: Drew Adams <drew.adams@oracle.com> > Cc: 14843@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. ^ permalink raw reply [flat|nested] 10+ messages in thread
[parent not found: <<e1139e17-abfc-4da6-a255-23f8e781bbfa@default>]
[parent not found: <<83sizl54mu.fsf@gnu.org>]
* bug#14843: 24.3.50; `line-move', `line-move-visual' need doc strings [not found] ` <<83sizl54mu.fsf@gnu.org> @ 2013-07-11 18:50 ` Drew Adams 2013-07-11 19:06 ` Eli Zaretskii 0 siblings, 1 reply; 10+ messages in thread From: Drew Adams @ 2013-07-11 18:50 UTC (permalink / raw) To: Eli Zaretskii, Drew Adams; +Cc: 14843 > > 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#14843: 24.3.50; `line-move', `line-move-visual' need doc strings 2013-07-11 18:50 ` Drew Adams @ 2013-07-11 19:06 ` Eli Zaretskii 0 siblings, 0 replies; 10+ messages in thread From: Eli Zaretskii @ 2013-07-11 19:06 UTC (permalink / raw) To: Drew Adams; +Cc: 14843 > Date: Thu, 11 Jul 2013 11:50:06 -0700 (PDT) > From: Drew Adams <drew.adams@oracle.com> > Cc: 14843@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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#14843: 24.3.50; `line-move', `line-move-visual' need doc strings @ 2013-07-11 15:40 Drew Adams 2013-07-11 18:32 ` Eli Zaretskii 2013-07-11 23:04 ` Stefan Monnier 0 siblings, 2 replies; 10+ messages in thread From: Drew Adams @ 2013-07-11 15:40 UTC (permalink / raw) To: 14843 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@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'' ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#14843: 24.3.50; `line-move', `line-move-visual' need doc strings 2013-07-11 15:40 Drew Adams @ 2013-07-11 18:32 ` Eli Zaretskii 2013-07-11 23:04 ` Stefan Monnier 1 sibling, 0 replies; 10+ messages in thread From: Eli Zaretskii @ 2013-07-11 18:32 UTC (permalink / raw) To: Drew Adams; +Cc: 14843 > Date: Thu, 11 Jul 2013 08:40:49 -0700 (PDT) > From: Drew Adams <drew.adams@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? ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#14843: 24.3.50; `line-move', `line-move-visual' need doc strings 2013-07-11 15:40 Drew Adams 2013-07-11 18:32 ` Eli Zaretskii @ 2013-07-11 23:04 ` Stefan Monnier 2014-02-08 6:28 ` Lars Ingebrigtsen 1 sibling, 1 reply; 10+ messages in thread From: Stefan Monnier @ 2013-07-11 23:04 UTC (permalink / raw) To: Drew Adams; +Cc: 14843 > They need doc strings, with complete descriptions of their parameters. Agreed. Stefan "Looking forward to your corresponding commit" ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#14843: 24.3.50; `line-move', `line-move-visual' need doc strings 2013-07-11 23:04 ` Stefan Monnier @ 2014-02-08 6:28 ` Lars Ingebrigtsen 0 siblings, 0 replies; 10+ messages in thread From: Lars Ingebrigtsen @ 2014-02-08 6:28 UTC (permalink / raw) To: Stefan Monnier; +Cc: 14843 Stefan Monnier <monnier@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/ ^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2014-02-08 6:28 UTC | newest]
Thread overview: 10+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
[not found] <<43758336-46c0-42cf-a16d-6412c5e003d8@default>
[not found] ` <<83r4f46hmm.fsf@gnu.org>
2013-07-11 20:52 ` bug#14843: 24.3.50; `line-move', `line-move-visual' need doc strings Drew Adams
2013-07-12 6:54 ` Eli Zaretskii
[not found] <<83e00f63-4458-4901-8816-4875f599d9cc@default>
[not found] ` <<83li5c5kvp.fsf@gnu.org>
2013-07-12 8:26 ` Drew Adams
2013-07-12 9:19 ` Eli Zaretskii
[not found] <<e1139e17-abfc-4da6-a255-23f8e781bbfa@default>
[not found] ` <<83sizl54mu.fsf@gnu.org>
2013-07-11 18:50 ` Drew Adams
2013-07-11 19:06 ` Eli Zaretskii
2013-07-11 15:40 Drew Adams
2013-07-11 18:32 ` Eli Zaretskii
2013-07-11 23:04 ` Stefan Monnier
2014-02-08 6:28 ` Lars Ingebrigtsen
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).