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

Previous Next

Full log

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.

Previous Next

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