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#15547: 24.3.50; doc string of `isearch-cmds' Date: Sat, 8 Feb 2014 18:42:41 -0800 (PST) Message-ID: <10ad2e6b-7393-4ecd-9672-527484aee22d@default> References: <60fb0470-bd15-447f-8e03-9ffc8eb57d0e@default> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1391913820 5340 80.91.229.3 (9 Feb 2014 02:43:40 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 9 Feb 2014 02:43:40 +0000 (UTC) To: 15547@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Feb 09 03:43:47 2014 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 1WCKN0-00020P-Kt for geb-bug-gnu-emacs@m.gmane.org; Sun, 09 Feb 2014 03:43:46 +0100 Original-Received: from localhost ([::1]:48873 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WCKN0-0007Ui-9F for geb-bug-gnu-emacs@m.gmane.org; Sat, 08 Feb 2014 21:43:46 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54285) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WCKMR-0006qI-1E for bug-gnu-emacs@gnu.org; Sat, 08 Feb 2014 21:43:19 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WCKMI-00052v-DY for bug-gnu-emacs@gnu.org; Sat, 08 Feb 2014 21:43:10 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:44520) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WCKMI-00052r-AL for bug-gnu-emacs@gnu.org; Sat, 08 Feb 2014 21:43:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1WCKMH-000791-TY for bug-gnu-emacs@gnu.org; Sat, 08 Feb 2014 21:43:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 09 Feb 2014 02:43:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15547 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 15547-submit@debbugs.gnu.org id=B15547.139191376827439 (code B ref 15547); Sun, 09 Feb 2014 02:43:01 +0000 Original-Received: (at 15547) by debbugs.gnu.org; 9 Feb 2014 02:42:48 +0000 Original-Received: from localhost ([127.0.0.1]:58539 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WCKM3-00078V-GW for submit@debbugs.gnu.org; Sat, 08 Feb 2014 21:42:47 -0500 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:43722) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WCKM1-00078N-Bz for 15547@debbugs.gnu.org; Sat, 08 Feb 2014 21:42:45 -0500 Original-Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id s192gijh004864 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for <15547@debbugs.gnu.org>; Sun, 9 Feb 2014 02:42:44 GMT Original-Received: from aserz7022.oracle.com (aserz7022.oracle.com [141.146.126.231]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s192ghTP024531 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for <15547@debbugs.gnu.org>; Sun, 9 Feb 2014 02:42:44 GMT Original-Received: from abhmp0011.oracle.com (abhmp0011.oracle.com [141.146.116.17]) by aserz7022.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s192ghep024527 for <15547@debbugs.gnu.org>; Sun, 9 Feb 2014 02:42:43 GMT In-Reply-To: <60fb0470-bd15-447f-8e03-9ffc8eb57d0e@default> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6680.5000 (x86)] X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.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:85015 Archived-At: > > > 1. The first element of the vector is missing from the > > > description. It is the symbol `cl-struct-isearch--state'. > > > The vector has 13 elements, not 12. >=20 > I don't think it should say "vector" at all. It's a list of > structs. That the structs are implemented internally as vectors > should be irrelevant. I'll change the doc string. No, it is not irrelevant. See below, about correspondences with important Isearch variables, as one indication. > > > 2. It would be a little clearer to say that the value is a *list* > > > that is *used* as a stack. >=20 > Uhm... I don't think that's necessary. > > > > 3. Better to just say "vectors", not "sets", since > > > the order is important (and the reader is right-away presented ^^^^^^^^^^^^^^^^^^^^^^ > > > with the vector description). These are vectors. They are sequences; they have order. > > And I forgot perhaps the most important of all: please describe > > each of the vector elements. Say what they correspond to, e.g., ^^^^^^^^^^^^^^^^^^^^^^^ > > `isearch--state-barrier' corresponds to variable `isearch-barrier' > > (which has a doc string describing it). Without knowing those correspondences the code is impenetrable, and anyone trying to make use of it (e.g., adapt parts of it) is at a loss. More generally, any Lisp programmer working with isearch code these days needs to understand the things I reported that are not clear. There are many people out there who write their own code that involves adaptation (and sometimes improvement) of distributed Emacs code. They invent new features and sometimes better ways of doing things. That is the point of free software, and Emacs in particular. Adding, rather than removing, obstacles to understanding is perverse. It is akin to obfuscating code. The Isearch code is particularly dense and deserves better documentation. Users deserve better.