bug#15547: 24.3.50; doc string of `isearch-cmds'

bug#15547: 24.3.50; doc string of `isearch-cmds'

[Drew Adams]

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'

bug#15547: 24.3.50; doc string of `isearch-cmds'

[Drew Adams]

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

bug#15547: 24.3.50; doc string of `isearch-cmds'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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/

bug#15547: 24.3.50; doc string of `isearch-cmds'

[Drew Adams]

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