GNU bug report logs - #2035
23.0.60; doc string of dired-read-shell-command

Previous Next

Full log

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Juanma Barranquero'" <lekktu <at> gmail.com>
Cc: <2035 <at> debbugs.gnu.org>
Subject: RE: bug#2035: 23.0.60; doc string of dired-read-shell-command
Date: Fri, 13 Feb 2009 07:09:23 -0800

> From: Juanma Barranquero Sent: Friday, February 13, 2009 3:49 AM
> > 1. The part about the "prefix arg", at least, doesn't make 
> > sense. This is not a command, and there is no reference in the code to
> > `current-prefix-arg'. The sentence is not clear to me, even ignoring
> > "prefix" - *how* does ARG indicate, in the prompt, which files are
> > affected?
> 
> It makes somewhat more sense if you look at the original version in
> dired-aux.el.
> 
> > 2. Argument FILES is not described (should be uppercase).
> 
> It is fixed in the dired-aux version :(
> 
> > 3. It's not clear (to me) what the last sentence is 
> > supposed to mean.
> 
> Is part of a comment in the original version.
> 
> All in all, I think the docstring should say: "This is an internal
> function." and little more. The info in the docstring should have
> stayed a comment IMHO.

It's not necessarily an internal function. It's a non-interactive function, but
there is no reason that other code can't also call it. 

The doc string should explain what the function does, as always (but not how it
does it).

Previous Next

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