Subject: bug#907: 23.0.60; doc string for dired-do-create-files

From: "Drew Adams" <[email-masked]>
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.