bug#11553: 24.0.97; doc string of `dired-mark-read-string'

bug#11553: 24.0.97; doc string of `dired-mark-read-string'

[Drew Adams]

The doc string includes this:
 
1. "ARG is normally the prefix argument for the calling command."
 
So what?  That doesn't tell you anything useful.  What is ARG for?  What
does it do?  Just say that it is passed to `dired-mark-prompt'.
 
2. "FILES should be a list of file names."
 
No.  That kind of help is no help at all.  FILES is the list of _marked_
files.
 
3. "DEFAULT-VALUE, if non-nil, should be a "standard" value or list
of such values, available via history commands.  Note that if the
user enters empty input, this function returns the empty string,
not DEFAULT-VALUE."
 
The first sentence: Does it say anything useful?  If so, it's not clear
to me.  It seems to be saying only that DEFAULT-VALUE is a default value
or list of default values.  It would be far clearer and actually helpful
if you just said that DEFAULT-VALUE is passed to `completing-read'.
 
IOW, do what you did for COLLECTION.  Just say that INITIAL,
DEFAULT-VALUE, and COLLECTION are passed to `completing-read'.  That
will provide a link to `completing-read', whose doc provides complete
and accurate descriptions of these arguments.
 
In GNU Emacs 24.0.97.1 (i386-mingw-nt5.1.2600)
 of 2012-05-16 on MARVIN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --no-opt --enable-checking --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include'
 

bug#11553: 24.0.97; doc string of `dired-mark-read-string'

[Drew Adams]

> 1. "ARG is normally the prefix argument for the calling command."
>  
> So what?  That doesn't tell you anything useful.  What is ARG 
> for?  What does it do?  Just say that it is passed to
> `dired-mark-prompt'.

Things are even worse than I thought.  The doc string of `dired-mark-prompt'
punts just as pitifully as that for `dired-mark-read-string' - the wording is
even the same.

What should be said about ARG and FILES for `dired-mark-prompt':

 "If ARG is nil then prompt to act on the number of files in FILES.
  If non-nil then prompt to act on the next N files, where N is the
  `prefix-numeric-value' of ARG."

 "FILES is the same as in `dired-mark-pop-up'."

(or repeat the definition of FILES from `dired-mark-pop-up')

bug#11553: 24.0.97; doc string of `dired-mark-read-string'

[Leo]

I think the comments are very good. I wonder if it is possible for you
write the patch directly? Thanks.

Leo

bug#11553: 24.0.97; doc string of `dired-mark-read-string'

[Drew Adams]

> The doc string includes this:
>  
> 1. "ARG ...
>  
> 2. "FILES ...
>  
> 3. "DEFAULT-VALUE ...

In addition, for PROMPT, it says only that the function prompts with PROMPT.

It should say that PROMPT is a string that is acceptable as the first argument
to `format', and that `format' is passed, as a second argument, the result of
applying `dired-mark-prompt' to ARG and FILES.

IOW, PROMPT is *not* a prompt string.  It is a format string used to create a
prompt string.

bug#11553: 24.0.97; doc string of `dired-mark-read-string'

[Chong Yidong]

Fixed in trunk.