Subject: 24.0.97; doc string of `dired-mark-read-string'

From: "Drew Adams" <[email-masked]>
Date: Thu, 24 May 2012 11:27:28 -0700

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'