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

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

> >>> This has apparently already been fixed.
> >>
> >> No, it has not.  The doc string has been changed, but the 
> >> bug report still applies.  Please read it.  What about the
> >> prefix argument?  This is not a command.  How can it have a
> >> prefix argument? Etc.
> >
> > It is passed `current-prefix-arg' in the use cases, so I 
> > think that's clear enough.
> 
> I fixed the remaining doc issues; closing.

Haven't yet seen your changes, Yidong, but the reply below to Lars apparently
did not make it to the thread - perhaps I forgot to use `Reply All'.  I hope its
points were proactively addressed by your fix.

It is incorrect to speak here (at all) about "prefix arg" or
`current-prefix-arg'.

Thx.

> Sent: Monday, July 11, 2011 9:13 AM  To: 'Lars Magne Ingebrigtsen'
> Subject: RE: 23.0.60; doc string of dired-read-shell-command
> 
> > >> This has apparently already been fixed.
> > >
> > > No, it has not.  The doc string has been changed, but the 
> > > bug report still applies.  Please read it.  What about the
> > > prefix argument?  This is not a command.  How can it have a
> > > prefix argument? Etc.
> > 
> > It is passed `current-prefix-arg' in the use cases, so I 
> > think that's clear enough.
> 
> Only a caller knows what it passes to `dired-read-shell-command'.
> The code for this function, and the doc string for this function,
> make no reference to `current-prefix-arg'.
> 
> If the code makes no reference to `current-prefix-arg' and 
> yet this function is always supposed to use 
> `current-prefix-arg', then it should not be passed as an arg 
> but should be hard-coded in the body.
> 
> If, OTOH, we want the argument ARG to be able to be something 
> other than the value of `current-prefix-arg', then we should 
> keep that parameter.  And if it is kept it needs to be 
> documented.  And it must not, in that case, be documented as 
> the "prefix arg" or `current-prefix-arg' or any such thing.  
> It must be documented in its own right: what is it for?  What 
> are its possible values?
> 
> This should be obvious.  This is the approach for any 
> function.  If we want always the same value, then don't pass 
> it as a paramter.  If we define a parameter then document it.