GNU bug report logs - #957
23.0.60; No doc string for Dired functions

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 957 in the body.
You can then email your comments to 957 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <emacs-pretest-bug <at> gnu.org>
Subject: 23.0.60; No doc string for Dired functions
Date: Wed, 10 Sep 2008 09:16:11 -0700

There is still no doc string for many useful Dired functions, from
things like `dired-repeat-overlines' to all of the tree Dired
non-interactive functions. At a minimum, the arguments should be
described in a doc string. Even some commands, like `dired-kill-line',
still have no doc.
 

In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-08-29 on LENNART-69DE564
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/g/include
-fno-crossjumping'
 

Message #10 received at 957 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Roland Winkler <Roland.Winkler <at> physik.uni-erlangen.de>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 957 <at> debbugs.gnu.org
Subject: Re: bug#957: 23.0.60; No doc string for Dired functions
Date: Thu, 11 Sep 2008 22:55:41 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:
> There is still no doc string for many useful Dired functions, from
> things like `dired-repeat-overlines' to all of the tree Dired
> non-interactive functions. At a minimum, the arguments should be
> described in a doc string. Even some commands, like `dired-kill-line',
> still have no doc.

I had promised to look into that. I am sorry for the delay.

Roland

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

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 957 <at> debbugs.gnu.org
Subject: Re: 23.0.60; No doc string for Dired functions
Date: Wed, 06 Jul 2011 20:27:45 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> There is still no doc string for many useful Dired functions, from
> things like `dired-repeat-overlines' to all of the tree Dired
> non-interactive functions. At a minimum, the arguments should be
> described in a doc string. Even some commands, like `dired-kill-line',
> still have no doc.

I've added a doc to `dired-kill-line', but I don't know what
`dired-repeat-overlines' is...

And the noninteractive functions don't need doc strings, really, do
they?

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

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 957 <at> debbugs.gnu.org
Subject: RE: 23.0.60; No doc string for Dired functions
Date: Wed, 6 Jul 2011 12:16:37 -0700

> > There is still no doc string for many useful Dired functions, from
> > things like `dired-repeat-overlines' to all of the tree Dired
> > non-interactive functions. At a minimum, the arguments should be
> > described in a doc string. Even some commands, like 
> > `dired-kill-line', still have no doc.
> 
> I've added a doc to `dired-kill-line'

Thank you.

> but I don't know what `dired-repeat-overlines' is...

All the more reason for it to get a doc string!

You don't know what it is, but _it_ should know what it is and be able to tell
us.  Someone (TM) will need to figure that out and give it a little help in the
self-explanation department.

> And the noninteractive functions don't need doc strings,
> really, do they?

Sure they do, in general.  Since when do we document only commands?

In the Dark Ages, doc strings were relatively more expensive (disk, memory,
etc.), and some minor functions were handled with only a comment.  Nowadays
there is rarely a good reason not to provide a doc string.

Emacs is the self-documenting editor.  If you must access the source code just
to get a description of a function from comments, or worse, to parse uncommented
code to figure out what a function does, then Emacs is not doing its
self-documenting job well.

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

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 957 <at> debbugs.gnu.org
Subject: Re: 23.0.60; No doc string for Dired functions
Date: Thu, 07 Jul 2011 18:30:18 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

>> but I don't know what `dired-repeat-overlines' is...
>
> All the more reason for it to get a doc string!

I meant that I couldn't find it.  :-)  But grepping for
`dired-repeat-over-lines' found it for me.

It, too, is an internal function, and I don't think it's worth
documenting all these.  They are only useful if you're doing dired
development, and then you presumably have the sources and can look at
the comments.

> Sure they do, in general.  Since when do we document only commands?
>
> In the Dark Ages, doc strings were relatively more expensive (disk, memory,
> etc.), and some minor functions were handled with only a comment.  Nowadays
> there is rarely a good reason not to provide a doc string.

I agree, but adding doc strings to purely internal functions that are
presumably self-explanatory to people who need to use them to develop
isn't all that useful.

It's not that I'm against adding doc strings (if somebody feels like
doing that), but it's not, in my opinion worth the time.  So I'm closing
this report.

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

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 957 <at> debbugs.gnu.org
Subject: RE: 23.0.60; No doc string for Dired functions
Date: Thu, 7 Jul 2011 09:43:04 -0700

> It's not that I'm against adding doc strings (if somebody feels like
> doing that), but it's not, in my opinion worth the time.  So 
> I'm closing this report.

Leave it open, if you're not against someone adding the doc strings.

Just because you don't have the time or aren't interested in adding the doc
strings does not mean that the bug should be closed.

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

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 957 <at> debbugs.gnu.org
Subject: Re: 23.0.60; No doc string for Dired functions
Date: Thu, 07 Jul 2011 18:48:57 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> Just because you don't have the time or aren't interested in adding the doc
> strings does not mean that the bug should be closed.

It is my opinion that doc strings will not be added to the internal
functions of dired.el through being unclosed in this bug tracker.

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