[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc
From: |
Drew Adams |
Subject: |
bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. |
Date: |
Tue, 17 May 2011 07:25:05 -0700 |
1. At a minimum, the doc string of `isearch-mode' should say something
like this:
FORWARD non-nil means forward search; nil means backward search.
REGEXP t means regexp search; nil means literal search.
OP-FUN means ???????
RECURSIVE-EDIT non-nil means recursive edit for a modal search.
WORD-P non-nil means word search; nil means ignore word boundaries.
And you can remove this sentence from the doc string - a function's doc
should, in general, not mention callers:
"It is called by the function `isearch-forward' and other related
functions."
(Also, some `isearch-mode' arguments should be renamed with `-P', to
indicate that they are boolean flags: FORWARD-P, REGEXP-P,
RECURSIVE-EDIT-P.)
OP-FUN: It corresponds to `isearch-op-fun', but there is no doc string
for `isearch-op-fun', and the accompanying source comment does not help
- it says only when `isearch-op-fun' is called, not what it is for or
how it is used.
2. Doc strings of `isearch-forward' etc. also need to describe their
args. E.g.
Non-interactively:
REGEXP-P means...
NO-RECURSIVE-EDIT means...
Again, NO-RECURSIVE-EDIT should be NO-RECURSIVE-EDIT-P, to indicate that
it is its truth value that is used (nil/non-nil).
3. More generally, isearch.el needs more and better doc strings.
In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
of 2011-05-16 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt --cflags
-Ic:/build/include'
- bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc.,
Drew Adams <=