[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#907: 23.0.60; doc string for dired-do-create-files
From: |
Drew Adams |
Subject: |
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.