GNU bug report logs - #11553
24.0.97; doc string of `dired-mark-read-string'

Previous Next

Full log

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.97; doc string of `dired-mark-read-string'
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'
 

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.