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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 11553 in the body.
You can then email your comments to 11553 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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'
 

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <11553 <at> debbugs.gnu.org>
Subject: RE: bug#11553: 24.0.97; doc string of `dired-mark-read-string'
Date: Thu, 24 May 2012 11:39:34 -0700

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

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

From: Leo <sdl.web <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#11553: 24.0.97; doc string of `dired-mark-read-string'
Date: Fri, 25 May 2012 10:14:50 +0800

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

Leo

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <11553 <at> debbugs.gnu.org>
Subject: RE: bug#11553: 24.0.97; doc string of `dired-mark-read-string'
Date: Sat, 2 Jun 2012 08:59:27 -0700

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

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

From: Chong Yidong <cyd <at> gnu.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 11553 <at> debbugs.gnu.org
Subject: Re: 24.0.97; doc string of `dired-mark-read-string'
Date: Fri, 22 Jun 2012 03:39:54 -0400

Fixed in trunk.

Previous Next

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