Subject: bug#2035: 23.0.60; doc string of dired-read-shell-command

From: "Drew Adams" <[email-masked]>
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).