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

["Drew Adams" <drew.adams@oracle.com>]

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