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#13923: 24.3.50; doc strings of Isearch commands Date: Mon, 29 Apr 2013 06:42:04 -0700 Message-ID: <9457FCDD57DC456A9526E04663C0009C@us.oracle.com> References: <87mwshvnp7.fsf@mail.jurta.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="US-ASCII" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1367242966 16304 80.91.229.3 (29 Apr 2013 13:42:46 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 29 Apr 2013 13:42:46 +0000 (UTC) Cc: 13923@debbugs.gnu.org To: "'Juri Linkov'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Apr 29 15:42:51 2013 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1UWoLy-0003wg-T3 for geb-bug-gnu-emacs@m.gmane.org; Mon, 29 Apr 2013 15:42:51 +0200 Original-Received: from localhost ([::1]:41236 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UWoLy-0006jI-I8 for geb-bug-gnu-emacs@m.gmane.org; Mon, 29 Apr 2013 09:42:50 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:56638) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UWoLv-0006iH-AX for bug-gnu-emacs@gnu.org; Mon, 29 Apr 2013 09:42:48 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UWoLt-00043l-OJ for bug-gnu-emacs@gnu.org; Mon, 29 Apr 2013 09:42:47 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:45789) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UWoLt-00043Z-LK for bug-gnu-emacs@gnu.org; Mon, 29 Apr 2013 09:42:45 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1UWoMA-0005HC-Jl for bug-gnu-emacs@gnu.org; Mon, 29 Apr 2013 09:43:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 29 Apr 2013 13:43:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 13923 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 13923-submit@debbugs.gnu.org id=B13923.136724296720199 (code B ref 13923); Mon, 29 Apr 2013 13:43:02 +0000 Original-Received: (at 13923) by debbugs.gnu.org; 29 Apr 2013 13:42:47 +0000 Original-Received: from localhost ([127.0.0.1]:49898 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UWoLu-0005Fd-91 for submit@debbugs.gnu.org; Mon, 29 Apr 2013 09:42:47 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:48432) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UWoLn-0005FF-Bq for 13923@debbugs.gnu.org; Mon, 29 Apr 2013 09:42:40 -0400 Original-Received: from ucsinet22.oracle.com (ucsinet22.oracle.com [156.151.31.94]) by userp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r3TDgJMJ012051 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 29 Apr 2013 13:42:19 GMT Original-Received: from userz7021.oracle.com (userz7021.oracle.com [156.151.31.85]) by ucsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r3TDgImd029805 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Mon, 29 Apr 2013 13:42:19 GMT Original-Received: from abhmt115.oracle.com (abhmt115.oracle.com [141.146.116.67]) by userz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r3TDgIqK027998; Mon, 29 Apr 2013 13:42:18 GMT Original-Received: from dradamslap1 (/10.159.75.228) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 29 Apr 2013 06:42:18 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <87mwshvnp7.fsf@mail.jurta.org> Thread-Index: Ac5EpeHdG0ENoYJBS/OqpNp/zQxtXwAOFe9Q X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: ucsinet22.oracle.com [156.151.31.94] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x 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:73821 Archived-At: > > The doc strings of `isearch-forward' etc. should describe > > each of the arguments. That includes arg NO-RECURSIVE-EDIT. > > This applies to all Isearch commands. > > The docstring of `isearch-forward' describes the whole > Isearch facility for interactive use with all its available > commands and keys. On its own, irrelevant. If you expect someone looking at the doc string for function `foo' to go to the doc string of function `bar' to get part of `foo's description, then provide a link from foo's doc to bar's, and make clear that the parameters correspond etc. > If this function is called non-interactively, it does not > return to the calling function until the search is done. > > that describes the effect of NO-RECURSIVE-EDIT. Does it say that that is a description of NO-RECURSIVE-EDIT? No. If that is what the intention is, please make the connection, explicitly, so user's do not have to guess that that is what you mean. A user should be able to scan or search the doc string for a parameter name, to find its description (especially when the doc string is long, as in this case). > > The doc string of `isearch-mode', especially, needs to > > describe each of its arguments. It currently describes > > none of them. > > This is described already in the Commentary section of isearch.el: Irrelevant. Which part of "doc string" is not clear? By "self-documenting editor", Emacs does not mean only that you can find some comments that might help in the source code. Emacs promises more than that.