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: Fri, 15 Jul 2011 07:43:01 -0700 Message-ID: <9E267A931BB54123AB074A0D0A97A823@us.oracle.com> References: 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 1310741963 24754 80.91.229.12 (15 Jul 2011 14:59:23 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 15 Jul 2011 14:59:23 +0000 (UTC) To: <8682@debbugs.gnu.org> Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Jul 15 16:59:19 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 1QhjrL-0003ce-4m for geb-bug-gnu-emacs@m.gmane.org; Fri, 15 Jul 2011 16:59:19 +0200 Original-Received: from localhost ([::1]:39743 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QhjrJ-0002qy-Rz for geb-bug-gnu-emacs@m.gmane.org; Fri, 15 Jul 2011 10:59:17 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:43466) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Qhjcb-00071X-5S for bug-gnu-emacs@gnu.org; Fri, 15 Jul 2011 10:44:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QhjcZ-0000F1-FU for bug-gnu-emacs@gnu.org; Fri, 15 Jul 2011 10:44:04 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:56429) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QhjcZ-0000Ew-84 for bug-gnu-emacs@gnu.org; Fri, 15 Jul 2011 10:44:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1QhjcZ-0002Ol-1V; Fri, 15 Jul 2011 10:44:03 -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: Fri, 15 Jul 2011 14:44:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 8682 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: notabug Original-Received: via spool by 8682-submit@debbugs.gnu.org id=B8682.13107410029148 (code B ref 8682); Fri, 15 Jul 2011 14:44:02 +0000 Original-Received: (at 8682) by debbugs.gnu.org; 15 Jul 2011 14:43:22 +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 1Qhjbs-0002NU-Lg for submit@debbugs.gnu.org; Fri, 15 Jul 2011 10:43:21 -0400 Original-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 Original-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 Original-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 Original-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 Original-Received: from dradamslap1 (/10.159.34.212) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 15 Jul 2011 07:43:01 -0700 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-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Fri, 15 Jul 2011 10:44:03 -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:49150 Archived-At: 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.