From unknown Sun Jun 22 22:42:03 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#8682 <8682@debbugs.gnu.org> To: bug#8682 <8682@debbugs.gnu.org> Subject: Status: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Reply-To: bug#8682 <8682@debbugs.gnu.org> Date: Mon, 23 Jun 2025 05:42:03 +0000 retitle 8682 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. reassign 8682 emacs submitter 8682 "Drew Adams" severity 8682 minor tag 8682 notabug thanks From debbugs-submit-bounces@debbugs.gnu.org Tue May 17 10:25:31 2011 Received: (at submit) by debbugs.gnu.org; 17 May 2011 14:25:31 +0000 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 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 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 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-4.2 required=5.0 tests=BAYES_00,RCVD_IN_DNSWL_MED, T_RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 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 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 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 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 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 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 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 Received: from dradamslap1 (/10.159.36.86) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 17 May 2011 07:25:09 -0700 From: "Drew Adams" To: Subject: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Date: Tue, 17 May 2011 07:25:05 -0700 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit 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-Received-From: 140.186.70.17 X-Spam-Score: -6.5 (------) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.5 (------) 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' From debbugs-submit-bounces@debbugs.gnu.org Tue May 17 10:39:39 2011 Received: (at 8682) by debbugs.gnu.org; 17 May 2011 14:39:39 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QMLQx-0001PU-CE for submit@debbugs.gnu.org; Tue, 17 May 2011 10:39:39 -0400 Received: from fencepost.gnu.org ([140.186.70.10]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QMLQt-0001PG-VM for 8682@debbugs.gnu.org; Tue, 17 May 2011 10:39:36 -0400 Received: from 213-159-126-200.fibertel.com.ar ([200.126.159.213]:50778 helo=ceviche.home) by fencepost.gnu.org with esmtpsa (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1QMLQo-00060U-9L; Tue, 17 May 2011 10:39:30 -0400 Received: by ceviche.home (Postfix, from userid 20848) id A77CB66140; Tue, 17 May 2011 11:39:26 -0300 (ART) From: Stefan Monnier To: "Drew Adams" Subject: Re: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Message-ID: References: Date: Tue, 17 May 2011 11:39:26 -0300 In-Reply-To: (Drew Adams's message of "Tue, 17 May 2011 07:25:05 -0700") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -6.0 (------) X-Debbugs-Envelope-To: 8682 Cc: 8682@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.0 (------) > (Also, some `isearch-mode' arguments should be renamed with `-P', to > indicate that they are boolean flags: FORWARD-P, REGEXP-P, > RECURSIVE-EDIT-P.) No. Stefan From debbugs-submit-bounces@debbugs.gnu.org Tue May 17 10:47:00 2011 Received: (at 8682) by debbugs.gnu.org; 17 May 2011 14:47:00 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QMLY4-0001Zv-4Q for submit@debbugs.gnu.org; Tue, 17 May 2011 10:47:00 -0400 Received: from rcsinet10.oracle.com ([148.87.113.121]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QMLY2-0001Zk-Lg for 8682@debbugs.gnu.org; Tue, 17 May 2011 10:46:59 -0400 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 p4HEklBM008877 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 17 May 2011 14:46:50 GMT 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 p4HEkk5k006073 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Tue, 17 May 2011 14:46:47 GMT Received: from abhmt016.oracle.com (abhmt016.oracle.com [141.146.116.25]) by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p4HEkfpI032230; Tue, 17 May 2011 09:46:41 -0500 Received: from dradamslap1 (/10.159.36.86) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 17 May 2011 07:46:40 -0700 From: "Drew Adams" To: "'Stefan Monnier'" References: Subject: RE: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Date: Tue, 17 May 2011 07:46:36 -0700 Message-ID: <3CD827EDF5994E3DB18AC6E3A422D7CE@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcwUoEC30ZrPaTocTz+0+wBdo0YC6AAAD34A X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6090 In-Reply-To: X-Source-IP: rtcsinet21.oracle.com [66.248.204.29] X-CT-RefId: str=0001.0A090203.4DD28A5C.00BC:SCFSTAT5015188,ss=1,fgs=0 X-Spam-Score: -6.5 (------) X-Debbugs-Envelope-To: 8682 Cc: 8682@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.5 (------) > > (Also, some `isearch-mode' arguments should be renamed with `-P', to > > indicate that they are boolean flags: FORWARD-P, REGEXP-P, > > RECURSIVE-EDIT-P.) > > No. Yes, I know your argument that you want to distinguish Boolean functions (even nullary) from Boolean-valued variables. Still, it is a useful convention that conveys information. If you don't like `-P' because you think it too closely conveys "predicate" (and you don't want to consider a variable as a nullary predicate), then choose another naming convention for this. It is quite helpful to suggest by a parameter's name that it represents a truth value: nil/non-nil. From debbugs-submit-bounces@debbugs.gnu.org Tue May 17 13:32:35 2011 Received: (at 8682) by debbugs.gnu.org; 17 May 2011 17:32:35 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QMO8I-0005Wz-ND for submit@debbugs.gnu.org; Tue, 17 May 2011 13:32:34 -0400 Received: from fencepost.gnu.org ([140.186.70.10]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QMO8G-0005Wo-GU for 8682@debbugs.gnu.org; Tue, 17 May 2011 13:32:33 -0400 Received: from 213-159-126-200.fibertel.com.ar ([200.126.159.213]:35266 helo=ceviche.home) by fencepost.gnu.org with esmtpsa (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1QMO8A-0002Mz-Oi; Tue, 17 May 2011 13:32:27 -0400 Received: by ceviche.home (Postfix, from userid 20848) id C536466131; Tue, 17 May 2011 14:32:23 -0300 (ART) From: Stefan Monnier To: "Drew Adams" Subject: Re: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Message-ID: References: <3CD827EDF5994E3DB18AC6E3A422D7CE@us.oracle.com> Date: Tue, 17 May 2011 14:32:23 -0300 In-Reply-To: <3CD827EDF5994E3DB18AC6E3A422D7CE@us.oracle.com> (Drew Adams's message of "Tue, 17 May 2011 07:46:36 -0700") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -6.0 (------) X-Debbugs-Envelope-To: 8682 Cc: 8682@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.0 (------) > If you don't like `-P' because you think it too closely conveys > "predicate" (and you don't want to consider a variable as a nullary > predicate), then choose another naming convention for this. It is > quite helpful to suggest by a parameter's name that it represents > a truth value: nil/non-nil. `forward' works just fine, `recursive' as well. I agree that `regexp' isn't quite as clear because it's a substantive so it could also be understood to carry a regular expression, so you may prefer `use-regexp' or something like that. Stefan From debbugs-submit-bounces@debbugs.gnu.org Tue May 17 15:12:24 2011 Received: (at 8682) by debbugs.gnu.org; 17 May 2011 19:12:24 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QMPgu-0007jV-AP for submit@debbugs.gnu.org; Tue, 17 May 2011 15:12:24 -0400 Received: from rcsinet10.oracle.com ([148.87.113.121]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QMPgr-0007jI-Sa for 8682@debbugs.gnu.org; Tue, 17 May 2011 15:12:22 -0400 Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id p4HJCDPB000531 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 17 May 2011 19:12:15 GMT Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p4HJCCie002585 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Tue, 17 May 2011 19:12:12 GMT Received: from abhmt005.oracle.com (abhmt005.oracle.com [141.146.116.14]) by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p4HJC6NU002091; Tue, 17 May 2011 14:12:06 -0500 Received: from dradamslap1 (/10.159.39.125) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 17 May 2011 12:12:06 -0700 From: "Drew Adams" To: "'Stefan Monnier'" References: <3CD827EDF5994E3DB18AC6E3A422D7CE@us.oracle.com> Subject: RE: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Date: Tue, 17 May 2011 12:12:02 -0700 Message-ID: <07DD6196F9C34A72821A336E6764639D@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: AcwUuGnk34o00TTnTfSZmO8pUCwfBAADb2EA X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6090 X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090207.4DD2C890.004F:SCFMA922111,ss=1,fgs=0 X-Spam-Score: -6.5 (------) X-Debbugs-Envelope-To: 8682 Cc: 8682@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.5 (------) > > If you don't like `-P' because you think it too closely conveys > > "predicate" (and you don't want to consider a variable as a nullary > > predicate), then choose another naming convention for this. It is > > quite helpful to suggest by a parameter's name that it represents > > a truth value: nil/non-nil. > > `forward' works just fine, `recursive' as well. > I agree that `regexp' isn't quite as clear because it's a > substantive so > it could also be understood to carry a regular expression, so you may > prefer `use-regexp' or something like that. No, the point was to have a convention that suggests the Boolean-valuedness irrespective of the rest of the parameter name. Anyway, this is not the most important part of this bug report. From debbugs-submit-bounces@debbugs.gnu.org Fri Jul 15 09:40:23 2011 Received: (at control) by debbugs.gnu.org; 15 Jul 2011 13:40:24 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Qhicx-0006KE-Ea for submit@debbugs.gnu.org; Fri, 15 Jul 2011 09:40:23 -0400 Received: from hermes.netfonds.no ([80.91.224.195]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Qhicw-0006Jl-0N for control@debbugs.gnu.org; Fri, 15 Jul 2011 09:40:22 -0400 Received: from cm-84.215.51.58.getinternet.no ([84.215.51.58] helo=quimbies.gnus.org) by hermes.netfonds.no with esmtpsa (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.72) (envelope-from ) id 1Qhick-00023U-Ux for control@debbugs.gnu.org; Fri, 15 Jul 2011 15:40:11 +0200 Date: Fri, 15 Jul 2011 15:40:10 +0200 Message-Id: To: control@debbugs.gnu.org From: Lars Magne Ingebrigtsen Subject: control message for bug #8682 X-MailScanner-ID: 1Qhick-00023U-Ux X-Netfonds-MailScanner: Found to be clean X-Netfonds-MailScanner-From: larsi@gnus.org MailScanner-NULL-Check: 1311342011.28038@DwlbyU72Vy3D/U7iRfVhEQ X-Spam-Status: No X-Spam-Score: -2.7 (--) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.7 (--) tags 8682 notabug close 8682 From debbugs-submit-bounces@debbugs.gnu.org Fri Jul 15 09:48:07 2011 Received: (at 8682) by debbugs.gnu.org; 15 Jul 2011 13:48:07 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QhikN-0007N1-BF for submit@debbugs.gnu.org; Fri, 15 Jul 2011 09:48:07 -0400 Received: from hermes.netfonds.no ([80.91.224.195]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QhikE-0007ME-Av for 8682@debbugs.gnu.org; Fri, 15 Jul 2011 09:47:58 -0400 Received: from cm-84.215.51.58.getinternet.no ([84.215.51.58] helo=quimbies.gnus.org) by hermes.netfonds.no with esmtpsa (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.72) (envelope-from ) id 1Qhik3-0002F0-4a; Fri, 15 Jul 2011 15:47:43 +0200 From: Lars Magne Ingebrigtsen To: "Drew Adams" Subject: Re: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. In-Reply-To: (Drew Adams's message of "Tue, 17 May 2011 07:25:05 -0700") Date: Fri, 15 Jul 2011 15:40:06 +0200 Message-ID: References: User-Agent: Gnus/5.110018 (No Gnus v0.18) Emacs/24.0.50 (gnu/linux) X-Now-Playing: Joni Mitchell's _Ladies of the Canyon_: "The Circle Game" X-Hashcash: 1:23:110715:8682@debbugs.gnu.org::SChQOFAlhIIfoNzn:000000000000000000000000000000000000000008d3w X-Hashcash: 1:23:110715:drew.adams@oracle.com::K2LMkAfVCu+wZYge:0000000000000000000000000000000000000000QA9A MIME-Version: 1.0 Content-Type: text/plain X-MailScanner-ID: 1Qhik3-0002F0-4a X-Netfonds-MailScanner: Found to be clean X-Netfonds-MailScanner-From: larsi@gnus.org MailScanner-NULL-Check: 1311342463.23962@mFGHXHsEsklUdFFgZ209vQ X-Spam-Status: No X-Spam-Score: -2.7 (--) X-Debbugs-Envelope-To: 8682 Cc: 8682@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.7 (--) "Drew Adams" writes: > 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. It's an internal function. If you're not an isearch hacker, you'll never see it, and if you are, you will know what those parameters mean. The only thing that's useful in that doc string is the thing that's already there, and which you want removed: > 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." > 2. Doc strings of `isearch-forward' etc. also need to describe their > args. E.g. > > Non-interactively: > REGEXP-P means... > NO-RECURSIVE-EDIT means... I think any reasonable person would guess that REGEXP-P means "it's a regexp", and NO-RECURSIVE-EDIT means "we're not in a recursive edit". So I'm closing this report. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog http://lars.ingebrigtsen.no/ From unknown Sun Jun 22 22:42:03 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: Did not alter fixed versions and reopened. Date: Fri, 15 Jul 2011 14:41:01 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # Did not alter fixed versions and reopened. thanks # This fakemail brought to you by your local debbugs # administrator From debbugs-submit-bounces@debbugs.gnu.org Fri Jul 15 10:43:21 2011 Received: (at 8682) by debbugs.gnu.org; 15 Jul 2011 14:43:22 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Qhjbs-0002NU-Lg for submit@debbugs.gnu.org; Fri, 15 Jul 2011 10:43:21 -0400 Received: from acsinet15.oracle.com ([141.146.126.227]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Qhjbn-0002NB-AV for 8682@debbugs.gnu.org; Fri, 15 Jul 2011 10:43:16 -0400 Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by acsinet15.oracle.com (Switch-3.4.4/Switch-3.4.4) with ESMTP id p6FEh7oi001386 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for <8682@debbugs.gnu.org>; Fri, 15 Jul 2011 14:43:09 GMT Received: from acsmt358.oracle.com (acsmt358.oracle.com [141.146.40.158]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p6FEh68x019817 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for <8682@debbugs.gnu.org>; Fri, 15 Jul 2011 14:43:07 GMT Received: from abhmt112.oracle.com (abhmt112.oracle.com [141.146.116.64]) by acsmt358.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p6FEh19Y011992 for <8682@debbugs.gnu.org>; Fri, 15 Jul 2011 09:43:01 -0500 Received: from dradamslap1 (/10.159.34.212) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 15 Jul 2011 07:43:01 -0700 From: "Drew Adams" To: <8682@debbugs.gnu.org> References: Subject: RE: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Date: Fri, 15 Jul 2011 07:43:01 -0700 Message-ID: <9E267A931BB54123AB074A0D0A97A823@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: AcwUnjehd+tssDUJS7SZWstyGKGaCwuXc5kg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6109 X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090207.4E2051FD.006F:SCFMA922111,ss=1,re=-4.000,fgs=0 X-Spam-Score: -4.2 (----) X-Debbugs-Envelope-To: 8682 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -4.2 (----) Reopening. None of the issues raised in the bug report have been addressed. The thread was simply side-tracked by Stefan concentrating on suggested parameter names. Then along comes Lars and just closes the bug, apparently not reading the report or paying no attention to what it says. The bug report is not about the parameter names used - there were only parenthetical remarks about the names. Call the parameters whatever you like. The bug is about undocumented parameters, poorly documented parameters, inappropriate statements about calling functions, missing doc, and inadequate doc. Please read the report. This should be a no-brainer. I even suggested text for some of the individual parameter descriptions. Doc for a function needs to describe its parameters and say what it does. In many cases it also needs to describe the return value. There is nothing new about this. > 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." > 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... > 3. More generally, isearch.el needs more and better doc strings. From debbugs-submit-bounces@debbugs.gnu.org Fri Jul 15 11:03:15 2011 Received: (at submit) by debbugs.gnu.org; 15 Jul 2011 15:03:15 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Qhjv5-0004aN-Eh for submit@debbugs.gnu.org; Fri, 15 Jul 2011 11:03:15 -0400 Received: from eggs.gnu.org ([140.186.70.92]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Qhjum-0004Z8-No for submit@debbugs.gnu.org; Fri, 15 Jul 2011 11:02:56 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Qhjuc-0004N9-2M for submit@debbugs.gnu.org; Fri, 15 Jul 2011 11:02:47 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-4.2 required=5.0 tests=BAYES_00,RCVD_IN_DNSWL_MED, RP_MATCHES_RCVD autolearn=unavailable version=3.3.1 Received: from lists.gnu.org ([140.186.70.17]:40965) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Qhjub-0004Mx-Ov for submit@debbugs.gnu.org; Fri, 15 Jul 2011 11:02:41 -0400 Received: from eggs.gnu.org ([140.186.70.92]:54426) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QhjuW-00047k-Up for bug-gnu-emacs@gnu.org; Fri, 15 Jul 2011 11:02:41 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QhjuR-0004Ki-DM for bug-gnu-emacs@gnu.org; Fri, 15 Jul 2011 11:02:35 -0400 Received: from lo.gmane.org ([80.91.229.12]:37087) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QhjuQ-0004KE-LE for bug-gnu-emacs@gnu.org; Fri, 15 Jul 2011 11:02:31 -0400 Received: from list by lo.gmane.org with local (Exim 4.69) (envelope-from ) id 1QhjuP-0005Ug-0J for bug-gnu-emacs@gnu.org; Fri, 15 Jul 2011 17:02:29 +0200 Received: from cm-84.215.51.58.getinternet.no ([84.215.51.58]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Fri, 15 Jul 2011 17:02:28 +0200 Received: from larsi by cm-84.215.51.58.getinternet.no with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Fri, 15 Jul 2011 17:02:28 +0200 X-Injected-Via-Gmane: http://gmane.org/ Mail-Followup-To: bug-gnu-emacs@gnu.org To: bug-gnu-emacs@gnu.org From: Lars Magne Ingebrigtsen Subject: Re: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Date: Fri, 15 Jul 2011 17:02:10 +0200 Organization: Programmerer Ingebrigtsen Lines: 17 Message-ID: References: <9E267A931BB54123AB074A0D0A97A823@us.oracle.com> Mime-Version: 1.0 Content-Type: text/plain X-Complaints-To: usenet@dough.gmane.org X-Gmane-NNTP-Posting-Host: cm-84.215.51.58.getinternet.no Face: iVBORw0KGgoAAAANSUhEUgAAADAAAAAwBAMAAAClLOS0AAAAIVBMVEUwMi75+eydo5BgZlT+ //L+//h/gm7+//v////BzMj+//Y1EW/uAAACIUlEQVQ4jZ2Uv6vbMBDHDwSGjIIseVORQeBNWCDI +MBdshVecOkULBBkb7Dp1qHYqz0UtDsU8lf2K8tx/B7p0oP4HH10P3y6E/Eo2+KdvHLiQd/ucj1O ch1faVvc/9VlWdc1fpfy+A3ggPV6JU14XAKYF7ooTdN1bX0paHudtnVraet6pG0ZQVOvQAPwAsB7 zvsdf5g1s0Xvd33v+6+L0d2ViJINrnJCVNkCnNPaOOtOFETvPwBnFGnSRm3eAV1JV0lFcHhGvm8z sFpnVgurEgCP6G9TutoEV1o7oXOR+QiCBTGrmCNWuUwMEcQYlEhiJ5ZIK6z3vo/gD4ARihHLUpZn DxA+0PzWyN+ciJ39bgWGRKTEtFJE+cMCZZd2wBpTBo8MdWu6Fll9Bgi1YIacIuazYBEAggtiCCG1 U6hA3s8guAqlYz4V0Crp/QLSkNPGpywUdwFwlRJZpQUiKU1sDbRLmc11yIzoXiuATzgEsnsdD0ou oDthH5m9zYMms1S3OwUn9uxkBaLoHGOgJAp5GltVQoYEzH4GXa2yxElrK3QKPl4voM0F1qwyQsgH eEF7MuFwuMoAS4TbzKBrVTUVBR1UWdIqggM61vc7HwRqGAafLWAlP4FDdb9/BL/4F86fWdwn5J9g /B9QPwNon0P5jGDOi3I15IunHwDTnLdx1JsWoxzmfLoycLccg9nlcpw03m7FfPsUxeE2Tvo2Yt9Y cP4XtEekOQ6R9KgAAAAASUVORK5CYII= Mail-Copies-To: never X-Now-Playing: Joni Mitchell's _Mingus_ User-Agent: Gnus/5.110018 (No Gnus v0.18) Emacs/24.0.50 (gnu/linux) Cancel-Lock: sha1:Fnmyr9YKZ07h/wUnDbMg2rz1fSc= 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-Received-From: 140.186.70.17 X-Spam-Score: -4.3 (----) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -4.3 (----) "Drew Adams" writes: > Reopening. None of the issues raised in the bug report have been > addressed. The thread was simply side-tracked by Stefan concentrating > on suggested parameter names. Then along comes Lars and just closes > the bug, apparently not reading the report or paying no attention to > what it says. I did read the report, and I disagreed that this was something that should be documented. Please don't reopen reports that I have closed. If the Emacs maintainers disagree about the closing, they can open it again. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog http://lars.ingebrigtsen.no/ From debbugs-submit-bounces@debbugs.gnu.org Fri Jul 15 11:03:19 2011 Received: (at 8682) by debbugs.gnu.org; 15 Jul 2011 15:03:19 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Qhjv9-0004aV-Cs for submit@debbugs.gnu.org; Fri, 15 Jul 2011 11:03:19 -0400 Received: from hermes.netfonds.no ([80.91.224.195]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Qhjuu-0004ZP-8c for 8682@debbugs.gnu.org; Fri, 15 Jul 2011 11:03:04 -0400 Received: from cm-84.215.51.58.getinternet.no ([84.215.51.58] helo=quimbies.gnus.org) by hermes.netfonds.no with esmtpsa (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.72) (envelope-from ) id 1Qhjuj-0004Aa-4I; Fri, 15 Jul 2011 17:02:49 +0200 From: Lars Magne Ingebrigtsen To: "Drew Adams" Subject: Re: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. In-Reply-To: <9E267A931BB54123AB074A0D0A97A823@us.oracle.com> (Drew Adams's message of "Fri, 15 Jul 2011 07:43:01 -0700") Date: Fri, 15 Jul 2011 17:02:45 +0200 Message-ID: References: <9E267A931BB54123AB074A0D0A97A823@us.oracle.com> User-Agent: Gnus/5.110018 (No Gnus v0.18) Emacs/24.0.50 (gnu/linux) Face: iVBORw0KGgoAAAANSUhEUgAAADAAAAAwBAMAAAClLOS0AAAAIVBMVEUwMi75+eydo5BgZlT+ //L+//h/gm7+//v////BzMj+//Y1EW/uAAACIUlEQVQ4jZ2Uv6vbMBDHDwSGjIIseVORQeBNWCDI +MBdshVecOkULBBkb7Dp1qHYqz0UtDsU8lf2K8tx/B7p0oP4HH10P3y6E/Eo2+KdvHLiQd/ucj1O ch1faVvc/9VlWdc1fpfy+A3ggPV6JU14XAKYF7ooTdN1bX0paHudtnVraet6pG0ZQVOvQAPwAsB7 zvsdf5g1s0Xvd33v+6+L0d2ViJINrnJCVNkCnNPaOOtOFETvPwBnFGnSRm3eAV1JV0lFcHhGvm8z sFpnVgurEgCP6G9TutoEV1o7oXOR+QiCBTGrmCNWuUwMEcQYlEhiJ5ZIK6z3vo/gD4ARihHLUpZn DxA+0PzWyN+ciJ39bgWGRKTEtFJE+cMCZZd2wBpTBo8MdWu6Fll9Bgi1YIacIuazYBEAggtiCCG1 U6hA3s8guAqlYz4V0Crp/QLSkNPGpywUdwFwlRJZpQUiKU1sDbRLmc11yIzoXiuATzgEsnsdD0ou oDthH5m9zYMms1S3OwUn9uxkBaLoHGOgJAp5GltVQoYEzH4GXa2yxElrK3QKPl4voM0F1qwyQsgH eEF7MuFwuMoAS4TbzKBrVTUVBR1UWdIqggM61vc7HwRqGAafLWAlP4FDdb9/BL/4F86fWdwn5J9g /B9QPwNon0P5jGDOi3I15IunHwDTnLdx1JsWoxzmfLoycLccg9nlcpw03m7FfPsUxeE2Tvo2Yt9Y cP4XtEekOQ6R9KgAAAAASUVORK5CYII= X-Now-Playing: Joni Mitchell's _Mingus_ X-Hashcash: 1:23:110715:drew.adams@oracle.com::hIFv3O16XRbwY9Rn:00000000000000000000000000000000000000009glj X-Hashcash: 1:23:110715:8682@debbugs.gnu.org::yxvD1NmxclcGV+q8:00000000000000000000000000000000000000000nNPd MIME-Version: 1.0 Content-Type: text/plain X-MailScanner-ID: 1Qhjuj-0004Aa-4I X-Netfonds-MailScanner: Found to be clean X-Netfonds-MailScanner-From: larsi@gnus.org MailScanner-NULL-Check: 1311346969.20787@ldM234Xd9oN3siprgy7XIA X-Spam-Status: No X-Spam-Score: -2.7 (--) X-Debbugs-Envelope-To: 8682 Cc: 8682@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.7 (--) "Drew Adams" writes: > Reopening. None of the issues raised in the bug report have been > addressed. The thread was simply side-tracked by Stefan concentrating > on suggested parameter names. Then along comes Lars and just closes > the bug, apparently not reading the report or paying no attention to > what it says. I did read the report, and I disagreed that this was something that should be documented. Please don't reopen reports that I have closed. If the Emacs maintainers disagree about the closing, they can open it again. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog http://lars.ingebrigtsen.no/ From debbugs-submit-bounces@debbugs.gnu.org Fri Jul 15 11:06:22 2011 Received: (at 8682) by debbugs.gnu.org; 15 Jul 2011 15:06:23 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QhjyA-0004fT-5b for submit@debbugs.gnu.org; Fri, 15 Jul 2011 11:06:22 -0400 Received: from acsinet15.oracle.com ([141.146.126.227]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Qhjy8-0004fH-An for 8682@debbugs.gnu.org; Fri, 15 Jul 2011 11:06:20 -0400 Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by acsinet15.oracle.com (Switch-3.4.4/Switch-3.4.4) with ESMTP id p6FF6C1S029409 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 15 Jul 2011 15:06:14 GMT Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p6FF6CsG028723 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Fri, 15 Jul 2011 15:06:12 GMT Received: from abhmt118.oracle.com (abhmt118.oracle.com [141.146.116.70]) by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p6FF66Ka015643; Fri, 15 Jul 2011 10:06:06 -0500 Received: from dradamslap1 (/10.159.34.212) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 15 Jul 2011 08:06:06 -0700 From: "Drew Adams" To: "'Lars Magne Ingebrigtsen'" References: Subject: RE: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Date: Fri, 15 Jul 2011 08:06:06 -0700 Message-ID: <5DED13DA31E94AF9BF6B244A80E299D4@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: AcxC9c4nkxmAmpzmRgu/9YUawys6FwACWh6Q X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6109 X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090209.4E205766.00B9:SCFMA922111,ss=1,re=-4.000,fgs=0 X-Spam-Score: -4.2 (----) X-Debbugs-Envelope-To: 8682 Cc: 8682@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -4.2 (----) > It's an internal function. "Internal" functions too deserve doc strings, in general. And nothing in Emacs is truly "internal". Emacs purposefully documents itself, at all levels. That documentation is available to all users interactively. Skip creating reasonable doc strings and you stab Emacs, the "self-documenting editor", in the back. It was only in the Dark Ages, when doc strings were expensive because hardware was expensive, that we used comments instead of doc strings for many "internal" functions. We should not be lazy and cop out wrt "internal" functions. There is no strict separation in Emacs (or GNU generally) between users and developers, between "internal" code and external use of that code. > The only thing that's useful in that doc string is the thing that's > already there, and which you want removed: > > > 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." No, that is not "useful". More importantly, it is generally a bad idea for a callee to call out who calls it. There are exceptional cases, but this is not one. From debbugs-submit-bounces@debbugs.gnu.org Fri Jul 15 12:56:55 2011 Received: (at 8682) by debbugs.gnu.org; 15 Jul 2011 16:56:56 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Qhlh9-0002LU-9I for submit@debbugs.gnu.org; Fri, 15 Jul 2011 12:56:55 -0400 Received: from mail-pz0-f41.google.com ([209.85.210.41]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Qhlh7-0002LI-9d for 8682@debbugs.gnu.org; Fri, 15 Jul 2011 12:56:53 -0400 Received: by pzk4 with SMTP id 4so1638867pzk.0 for <8682@debbugs.gnu.org>; Fri, 15 Jul 2011 09:56:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc:content-type:content-transfer-encoding; bh=1G2DF81odljUi6NpybEmZ8hGjinIHBPVxCu+LGlhiOI=; b=wD53hCaWrOk8btDfkd+2OCegHfpBkYRnB5iBIC2bkukU8n1h0/7ixOX2OHozSLhH2s ASXhKq1kuBUMhE/H7q0hpopQqtQpZev9aMh3BLDLw+uQ+sFkufy0xzq2H9P0rvEWVz/8 f/hi15TglSFy4n64Tp6O3kvpguHreNenH2Ick= Received: by 10.142.234.3 with SMTP id g3mr1556348wfh.423.1310749007157; Fri, 15 Jul 2011 09:56:47 -0700 (PDT) MIME-Version: 1.0 Received: by 10.142.144.4 with HTTP; Fri, 15 Jul 2011 09:56:07 -0700 (PDT) In-Reply-To: <5DED13DA31E94AF9BF6B244A80E299D4@us.oracle.com> References: <5DED13DA31E94AF9BF6B244A80E299D4@us.oracle.com> From: Juanma Barranquero Date: Fri, 15 Jul 2011 18:56:07 +0200 Message-ID: Subject: Re: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. To: Drew Adams Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -3.3 (---) X-Debbugs-Envelope-To: 8682 Cc: Lars Magne Ingebrigtsen , 8682@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -3.3 (---) On Fri, Jul 15, 2011 at 17:06, Drew Adams wrote: > "Internal" functions too deserve doc strings, in general. > > And nothing in Emacs is truly "internal". =C2=A0Emacs purposefully docume= nts itself, > at all levels. =C2=A0That documentation is available to all users interac= tively. Of course there are internal elisp functions. Many of them even use a convention of having two consecutive dashes in the name to mark that they are internal, but not all. And what makes them internal is that they are an implementation detail and could be removed, or changed beyond all recognition, at any moment. Documenting them past the simple "This is an internal function" leads the user-developer to falsely believe that they are part of the interface, but they are not. Otherwise, nothing could ever be changed but painstakingly and with lot of ugly compatibility code. Which is fine for the advertised interfaces, but not for every single function in every single package in lisp/**/*.el. First someone asks to document them all, then s/he will use them in some package, and finally s/he will complain harshly when they are deleted in some future release. Better to say clearly: don't do that, or do it under you own responsability, after looking at the code, and knowing full well that if you do you'll likely need to workaround changes in the future. (I'm not talking about the specific changes in this bug thread, but comments like "Nothing in Emacs is truly 'internal'" cannot be let pass unchallenged...) =C2=A0 =C2=A0 Juanma From debbugs-submit-bounces@debbugs.gnu.org Fri Jul 15 14:30:54 2011 Received: (at 8682) by debbugs.gnu.org; 15 Jul 2011 18:30:54 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QhnA5-0004Ta-TB for submit@debbugs.gnu.org; Fri, 15 Jul 2011 14:30:54 -0400 Received: from acsinet15.oracle.com ([141.146.126.227]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QhnA3-0004TO-E1 for 8682@debbugs.gnu.org; Fri, 15 Jul 2011 14:30:52 -0400 Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by acsinet15.oracle.com (Switch-3.4.4/Switch-3.4.4) with ESMTP id p6FIUhct001293 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 15 Jul 2011 18:30:45 GMT Received: from acsmt357.oracle.com (acsmt357.oracle.com [141.146.40.157]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p6FIUgmd017093 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Fri, 15 Jul 2011 18:30:43 GMT Received: from abhmt101.oracle.com (abhmt101.oracle.com [141.146.116.53]) by acsmt357.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p6FIUbIZ017891; Fri, 15 Jul 2011 13:30:37 -0500 Received: from dradamslap1 (/10.159.40.132) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 15 Jul 2011 11:30:37 -0700 From: "Drew Adams" To: "'Juanma Barranquero'" References: <5DED13DA31E94AF9BF6B244A80E299D4@us.oracle.com> Subject: RE: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Date: Fri, 15 Jul 2011 11:30:33 -0700 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: AcxDEDQgLiB5qhYHTqKMs0xNSXO18AAA96qg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6109 X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090206.4E208755.0125:SCFMA922111,ss=1,re=-4.000,fgs=0 X-Spam-Score: -4.2 (----) X-Debbugs-Envelope-To: 8682 Cc: 'Lars Magne Ingebrigtsen' , 8682@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -4.2 (----) > > "Internal" functions too deserve doc strings, in general. > > > > And nothing in Emacs is truly "internal". =A0Emacs=20 > > purposefully documents itself, at all levels. =A0That documentation > > is available to all users interactively. >=20 > Of course there are internal elisp functions. Many of them even use a > convention of having two consecutive dashes in the name to mark that > they are internal, but not all. >=20 > And what makes them internal is that they are an implementation detail > and could be removed, or changed beyond all recognition, at any > moment. Documenting them past the simple "This is an internal > function" leads the user-developer to falsely believe that they are > part of the interface, but they are not. Otherwise, nothing could ever > be changed but painstakingly and with lot of ugly compatibility code. > Which is fine for the advertised interfaces, but not for every single > function in every single package in lisp/**/*.el. >=20 > First someone asks to document them all, then s/he will use them in > some package, and finally s/he will complain harshly when they are > deleted in some future release. Better to say clearly: don't do that, > or do it under you own responsability, after looking at the code, and > knowing full well that if you do you'll likely need to workaround > changes in the future. I actually agree with most of what you wrote, Juanma. And well put. I nevertheless maintain that nothing in Emacs is "_truly_" internal. And that even "internal" functions deserve doc strings, in general. Nothing is truly internal because Emacs is open. More than that - it is intentionally, proudly, exceptionally, emphatically, in-your-face open. = Emacs _wants_ to expose itself, at all levels, to _anyone_ interested. It is = the self-documenting editor. There is no rigid developer/user dichotomy. This is the essential contribution of Emacs (and GNU). We say = "self-documenting AND customizable/modifiable", but the former - more generally open = source code, implies the latter (modifiable). This is to be contrasted with non-free software, where everything that is not advertised via an external API = _is_ truly internal. That nothing is truly internal in Emacs does not preclude those = responsible for the Emacs mainline development from wanting to let users know that = function XYZ is "internal" in the sense that it is better for them not to count on = the current behavior, or the implementation, remaining the same in the = future. That is orthogonal to doc, in general (and please note when I say "in = general", like "truly"). It is not because we want to convey the message that a = function or variable is internal in the sense that it might easily be changed, = that we should not, in general, document that function or variable. Emacs code is open. Doc strings are like easy-to-get-to code comments - = and intentionally so. Instead of digging into the source code to see what a function's parameters and purpose/effect/use are, you can just hit `C-h = f'. But not all code comments, of course. Only those comments that describe = what a thing is for and what its interface (e.g. signature) is. Information = about implementation, which can be found in some code comments, is generally = not appropriate for doc strings. That is another part of the raison d'etre = of doc strings: describe just the API and purpose/effect/use, not the = implementation. And not documenting some internal function does _not_ obviate the = potential problem you cite, of users using it and unwisely expecting it not to = change etc. On the contrary, documentation can, in addition to describing the = parameters and purpose, explicitly point out that the function is likely to be changed = easily. Or as you put it: > Better to say clearly: don't do that, or do it under you own > responsability, after looking at the code, and knowing full > well that if you do you'll likely need to workaround > changes in the future. Almost right, but it is not either/or. What's wrong is your "Better = to". Better to document the function AND say that it might well change = ("internal"). This is open software - we don't win by trying to hide things or get = people to not notice them. Ignorance or misunderstanding about a function or variable is no Chinese = wall against misuse of it. Quite the contrary. > (I'm not talking about the specific changes in this bug thread Which is what we should get back to - specifics about _these_ doc = strings. Still, the general discussion can be useful, since "internal" seems to = be the excuse more and more for not documenting things correctly. No sense = fixing an incorrect statement, since a function is "internal". No sense = documenting a function at all, since it is "internal". There are a wide range of "internal" functions and variables. In = general, we should improve their doc and, in some cases, the code comments. An excuse such as `no user should care about this unless they are = hacking the Isearch code' ("if you're not an isearch hacker, you'll never see it") = is misguided. _Any_ user potentially hacks Isearch code. Not in the = distributed Emacs sources (isearch.el) perhaps, but in user code. The goal should not be to discourage Emacs users from borrowing, = adapting, hacking the Isearch code or any other Emacs source code. Quite the = contrary. This is what Emacs is about. It is the self-documenting, customizable = editor. It is fine to let users know that a given function might change. It is = not fine to try to discourage its use or reuse by obfuscating it or not helping = to make clear what it does. It's just code, and code wants to be copied, = changed, and reused. Isearch should make itself clear to users of all stripes, facilitating = their use, reuse, adaptation, and (who knows?) improvement or extension. Just = as we should make the code clear to facilitate the job of Emacs Dev = maintainers, so we should make it clear for Emacs users. And users are a larger and more = varied group than Emacs Dev. They deserve clear, well commented, well = documented code. This is regardless of the internal needs of Emacs Dev itself. It's not = about the bureaucracy (volunteer or not, and I include myself here) that = serves the people - it's about serving the people. It's not (only or mainly) about = making life easier for Emacs Dev. That's only a subsidiary requirement/goal. Yes, there are reasons for some functions to be more or less internal, = subject to unplanned implementation/interface change, etc. There are not often = reasons to not document what a function does and what its parameters are. Emacs source code is for everyone. When writing it, including its doc, = the target should be Emacs users, not just the code author or the relatively = small group of Emacs Dev maintainers. Yes, this is a radically different = perspective from non-free software development. We have met the user, and s?he is = us - and more. From debbugs-submit-bounces@debbugs.gnu.org Mon Jul 18 10:07:00 2011 Received: (at 8682) by debbugs.gnu.org; 18 Jul 2011 14:07:00 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QioTM-0004C2-GM for submit@debbugs.gnu.org; Mon, 18 Jul 2011 10:07:00 -0400 Received: from ironport2-out.teksavvy.com ([206.248.154.183] helo=ironport2-out.pppoe.ca) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QioTK-0004Bp-4e for 8682@debbugs.gnu.org; Mon, 18 Jul 2011 10:06:59 -0400 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: Av0EAEE9JE5MCqt8/2dsb2JhbABUp3N4iHzCGoY8BJ8nhDA X-IronPort-AV: E=Sophos;i="4.67,222,1309752000"; d="scan'208";a="126495165" Received: from 76-10-171-124.dsl.teksavvy.com (HELO ceviche.home) ([76.10.171.124]) by ironport2-out.pppoe.ca with ESMTP/TLS/ADH-AES256-SHA; 18 Jul 2011 10:06:52 -0400 Received: by ceviche.home (Postfix, from userid 20848) id 3A93A6660D; Mon, 18 Jul 2011 10:06:52 -0400 (EDT) From: Stefan Monnier To: "Drew Adams" Subject: Re: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Message-ID: References: <9E267A931BB54123AB074A0D0A97A823@us.oracle.com> Date: Mon, 18 Jul 2011 10:06:52 -0400 In-Reply-To: <9E267A931BB54123AB074A0D0A97A823@us.oracle.com> (Drew Adams's message of "Fri, 15 Jul 2011 07:43:01 -0700") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.1 (--) X-Debbugs-Envelope-To: 8682 Cc: 8682@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.1 (--) > The bug is about undocumented parameters, poorly documented parameters, Sure. Please send us a suggested patch, Stefan From debbugs-submit-bounces@debbugs.gnu.org Mon Jul 18 10:13:28 2011 Received: (at 8682) by debbugs.gnu.org; 18 Jul 2011 14:13:29 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QioZc-0004Kt-B6 for submit@debbugs.gnu.org; Mon, 18 Jul 2011 10:13:28 -0400 Received: from rcsinet15.oracle.com ([148.87.113.117]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QioZZ-0004Kg-I8 for 8682@debbugs.gnu.org; Mon, 18 Jul 2011 10:13:26 -0400 Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by rcsinet15.oracle.com (Switch-3.4.4/Switch-3.4.4) with ESMTP id p6IEDHPr001315 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 18 Jul 2011 14:13:19 GMT Received: from acsmt357.oracle.com (acsmt357.oracle.com [141.146.40.157]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p6IEDHi2025853 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 18 Jul 2011 14:13:17 GMT Received: from abhmt112.oracle.com (abhmt112.oracle.com [141.146.116.64]) by acsmt357.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p6IEDB13010866; Mon, 18 Jul 2011 09:13:11 -0500 Received: from dradamslap1 (/10.159.41.201) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 18 Jul 2011 07:13:11 -0700 From: "Drew Adams" To: "'Stefan Monnier'" References: <9E267A931BB54123AB074A0D0A97A823@us.oracle.com> Subject: RE: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Date: Mon, 18 Jul 2011 07:13:01 -0700 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6109 In-Reply-To: Thread-Index: AcxFU/as0c/p7wvFR1CA/ihAZLn4uAAAGwoQ X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090208.4E243F7F.00C1:SCFMA922111,ss=1,re=-4.000,fgs=0 X-Spam-Score: -4.2 (----) X-Debbugs-Envelope-To: 8682 Cc: 8682@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -4.2 (----) > > The bug is about undocumented parameters, poorly documented > > parameters, > > Sure. Please send us a suggested patch, I don't know what the info about the functions and parameters etc. should be. That's why I'm asking for real doc strings. Someone familiar with this code should be able to supply the necessary info. If you then need help with wording (unlikely), I can try to help. It is the info content that is missing/incomplete/unclear. From debbugs-submit-bounces@debbugs.gnu.org Mon May 20 19:03:45 2013 Received: (at 8682-done) by debbugs.gnu.org; 20 May 2013 23:03:45 +0000 Received: from localhost ([127.0.0.1]:53552 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UeZ7I-0004aw-V4 for submit@debbugs.gnu.org; Mon, 20 May 2013 19:03:45 -0400 Received: from ps18281.dreamhost.com ([69.163.218.105]:59531 helo=ps18281.dreamhostps.com) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UeZ7G-0004an-6Z for 8682-done@debbugs.gnu.org; Mon, 20 May 2013 19:03:43 -0400 Received: from localhost (ps18281.dreamhostps.com [69.163.218.105]) by ps18281.dreamhostps.com (Postfix) with ESMTP id 755A6258B9E91C for <8682-done@debbugs.gnu.org>; Mon, 20 May 2013 16:03:05 -0700 (PDT) From: Juri Linkov To: 8682-done@debbugs.gnu.org Subject: Re: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Organization: JURTA References: <9E267A931BB54123AB074A0D0A97A823@us.oracle.com> Date: Tue, 21 May 2013 01:50:58 +0300 In-Reply-To: (Drew Adams's message of "Mon, 18 Jul 2011 07:13:01 -0700") Message-ID: <87ppwlcmed.fsf@mail.jurta.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: 0.8 (/) X-Debbugs-Envelope-To: 8682-done X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -1.9 (-) Version: 24.3.50 This was fixed recently in bug#13923, so I'm closing this report. From unknown Sun Jun 22 22:42:03 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Tue, 18 Jun 2013 11:24:03 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator