GNU bug report logs - #8682
24.0.50; doc strings of `isearch-mode', `isearch-forward', etc.

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Juri Linkov <juri <at> jurta.org>
Cc: tracker <at> debbugs.gnu.org
Subject: bug#8682: closed (24.0.50; doc strings of `isearch-mode',
 `isearch-forward', etc.)
Date: Mon, 20 May 2013 23:04:02 +0000

[Message part 1 (text/plain, inline)]

Your message dated Tue, 21 May 2013 01:50:58 +0300
with message-id <87ppwlcmed.fsf <at> mail.jurta.org>
and subject line Re: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc.
has caused the debbugs.gnu.org bug report #8682,
regarding 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc.
to be marked as done.

(If you believe you have received this mail in error, please contact
help-debbugs <at> gnu.org.)


-- 
8682: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=8682
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 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'
 

[Message part 3 (message/rfc822, inline)]

From: Juri Linkov <juri <at> jurta.org>
To: 8682-done <at> debbugs.gnu.org
Subject: Re: bug#8682: 24.0.50;
	doc strings of `isearch-mode', `isearch-forward', etc.
Date: Tue, 21 May 2013 01:50:58 +0300

Version: 24.3.50

This was fixed recently in bug#13923, so I'm closing this report.

Previous Next

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