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

Previous Next

Full log

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.

Previous Next

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