GNU bug report logs - #15547
24.3.50; doc string of `isearch-cmds'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 15547 in the body.
You can then email your comments to 15547 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.3.50; doc string of `isearch-cmds'
Date: Sun, 6 Oct 2013 21:04:33 -0700 (PDT)

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.

2. It would be a little clearer to say that the value is a *list* that
is *used* as a stack.

3. Better to just say "vectors", not "sets", since the order is
important (and the reader is right-away presented with the vector
description).



In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-09-30 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking 'CFLAGS=-O0 -g3' CPPFLAGS=-DGLYPH_DEBUG=1'

Message #8 received at 15547 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: 15547 <at> debbugs.gnu.org
Subject: RE: bug#15547: 24.3.50; doc string of `isearch-cmds'
Date: Sun, 6 Oct 2013 21:55:19 -0700 (PDT)

> 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.
> 
> 2. It would be a little clearer to say that the value is a *list* that
> is *used* as a stack.
> 
> 3. Better to just say "vectors", not "sets", since the order is
> important (and the reader is right-away presented with the vector
> description).

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).

Message #11 received at 15547 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 15547 <at> debbugs.gnu.org
Subject: Re: bug#15547: 24.3.50; doc string of `isearch-cmds'
Date: Fri, 07 Feb 2014 19:59:23 -0800

Drew Adams <drew.adams <at> oracle.com> writes:

> 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.

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.

> 2. It would be a little clearer to say that the value is a *list* that
> is *used* as a stack.

Uhm...  I don't think that's necessary.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #16 received at 15547 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: 15547 <at> debbugs.gnu.org
Subject: RE: bug#15547: 24.3.50; doc string of `isearch-cmds'
Date: Sat, 8 Feb 2014 18:42:41 -0800 (PST)

> > > 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.
> 
> 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.
> 
> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.