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

[Drew Adams <drew.adams@oracle.com>]

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