GNU bug report logs - #907
23.0.60; doc string for dired-do-create-files

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 907 in the body.
You can then email your comments to 907 AT debbugs.gnu.org in the normal way.

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

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <emacs-pretest-bug <at> gnu.org>
Subject: 23.0.60; doc string for dired-do-create-files
Date: Sat, 6 Sep 2008 15:31:51 -0700

emacs -Q
Same problem exists in Emacs 22.2, BTW.
 
The doc string of dired-do-create-files refers several times to
`into-dir' (without quotes or uppercase). Nowhere is there any
explanation of what is mean by this, however. Presumably, it is either
a global variable or an argument?
 
This renders the doc string incomprehensible. About 2/3 of the doc
string concerns `into-dir', and it includes a seemingly ridiculously
complex explanation of arg HOW-TO, complete with
if-then-else-if-then-else-if-then-else-if-then-else (no
exaggeration!).
 
Please rewrite the doc string so that it is self-contained and
readable. It should not simply mirror the code but should make clear
to users what each argument is.
 

In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-08-29 on LENNART-69DE564
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/g/include
-fno-crossjumping'
 

Message #10 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <907 <at> debbugs.gnu.org>, <emacs-pretest-bug <at> gnu.org>
Subject: RE: bug#907: 23.0.60; doc string for dired-do-create-files
Date: Sat, 6 Sep 2008 15:55:26 -0700

I said:

> This renders the doc string incomprehensible. About 2/3 of the doc
> string concerns `into-dir', and it includes a seemingly ridiculously
> complex explanation of arg HOW-TO, complete with
> if-then-else-if-then-else-if-then-else-if-then-else (no
> exaggeration!).

I was a little mistaken. It's both a bit worse and a bit better than I thought.

The last if-then-else-if-then-else supposedly explains HOW-TO; the first
if-then-else-if-then-else supposedly explains `into-dir' (which is an internal,
local variable).

This is all backwards and not clear at all. What's needed is a single,
straightforward explanation of HOW-TO, with no reference to `into-dir'.

Looking at previous Emacs versions, I discovered that this doc string derives
from a comment that was in the Emacs 20 code. The comment, which referred to
local variable `into-dir', was simply copied to a (then missing) doc string.

The rest still applies: 

> Please rewrite the doc string so that it is self-contained and
> readable. It should not simply mirror the code but should make clear
> to users what each argument is.

Message #20 received at 907-done <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Chong Yidong <cyd <at> stupidchicken.com>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 907-done <at> debbugs.gnu.org
Subject: Re: 23.0.60; doc string for dired-do-create-files
Date: Wed, 22 Oct 2008 16:21:49 -0400

> The doc string of dired-do-create-files refers several times to
> `into-dir' (without quotes or uppercase). Nowhere is there any
> explanation of what is mean by this, however. Presumably, it is either
> a global variable or an argument?

Fixed, thanks.

Previous Next

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