From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Date: Tue, 17 May 2011 07:25:05 -0700 Message-ID: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1305642372 4267 80.91.229.12 (17 May 2011 14:26:12 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Tue, 17 May 2011 14:26:12 +0000 (UTC) To: 8682@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue May 17 16:26:08 2011 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1QMLDr-0006Ck-Sa for geb-bug-gnu-emacs@m.gmane.org; Tue, 17 May 2011 16:26:08 +0200 Original-Received: from localhost ([::1]:37570 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QMLDr-0000SZ-CU for geb-bug-gnu-emacs@m.gmane.org; Tue, 17 May 2011 10:26:07 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:60934) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QMLDn-0000SJ-P8 for bug-gnu-emacs@gnu.org; Tue, 17 May 2011 10:26:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QMLDm-0007cO-IE for bug-gnu-emacs@gnu.org; Tue, 17 May 2011 10:26:03 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:58142) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QMLDm-0007cG-Gq for bug-gnu-emacs@gnu.org; Tue, 17 May 2011 10:26:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1QMLDl-00015F-Td; Tue, 17 May 2011 10:26:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 17 May 2011 14:26:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 8682 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: Original-Received: via spool by submit@debbugs.gnu.org id=B.13056423314115 (code B ref -1); Tue, 17 May 2011 14:26:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 17 May 2011 14:25:31 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QMLDG-00014I-MN for submit@debbugs.gnu.org; Tue, 17 May 2011 10:25:31 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QMLDE-000143-TD for submit@debbugs.gnu.org; Tue, 17 May 2011 10:25:29 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QMLD8-0007KA-ON for submit@debbugs.gnu.org; Tue, 17 May 2011 10:25:23 -0400 Original-Received: from lists.gnu.org ([140.186.70.17]:49271) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QMLD8-0007K6-Mn for submit@debbugs.gnu.org; Tue, 17 May 2011 10:25:22 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:60793) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QMLD7-0000KD-O1 for bug-gnu-emacs@gnu.org; Tue, 17 May 2011 10:25:22 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QMLD6-0007Il-B2 for bug-gnu-emacs@gnu.org; Tue, 17 May 2011 10:25:21 -0400 Original-Received: from rcsinet10.oracle.com ([148.87.113.121]:53324) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QMLD6-0007Hu-1n for bug-gnu-emacs@gnu.org; Tue, 17 May 2011 10:25:20 -0400 Original-Received: from rtcsinet21.oracle.com (rtcsinet21.oracle.com [66.248.204.29]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id p4HEPG4n025225 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Tue, 17 May 2011 14:25:18 GMT Original-Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by rtcsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p4HEPFo7023347 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Tue, 17 May 2011 14:25:16 GMT Original-Received: from abhmt003.oracle.com (abhmt003.oracle.com [141.146.116.12]) by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p4HEP93h010099 for ; Tue, 17 May 2011 09:25:10 -0500 Original-Received: from dradamslap1 (/10.159.36.86) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 17 May 2011 07:25:09 -0700 X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcwUnjehd+tssDUJS7SZWstyGKGaCw== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6090 X-Source-IP: rtcsinet21.oracle.com [66.248.204.29] X-CT-RefId: str=0001.0A090205.4DD2854E.015E:SCFSTAT5015188,ss=1,fgs=0 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Tue, 17 May 2011 10:26:01 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:46512 Archived-At: 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'