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

Previous Next

Full log

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.

Previous Next

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