all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#15547: 24.3.50; doc string of `isearch-cmds'
@ 2013-10-07  4:04 Drew Adams
  2013-10-07  4:55 ` Drew Adams
  2014-02-08  3:59 ` Lars Ingebrigtsen
  0 siblings, 2 replies; 4+ messages in thread
From: Drew Adams @ 2013-10-07  4:04 UTC (permalink / raw)
  To: 15547

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'





^ permalink raw reply	[flat|nested] 4+ messages in thread

* bug#15547: 24.3.50; doc string of `isearch-cmds'
  2013-10-07  4:04 bug#15547: 24.3.50; doc string of `isearch-cmds' Drew Adams
@ 2013-10-07  4:55 ` Drew Adams
  2014-02-09  2:42   ` Drew Adams
  2014-02-08  3:59 ` Lars Ingebrigtsen
  1 sibling, 1 reply; 4+ messages in thread
From: Drew Adams @ 2013-10-07  4:55 UTC (permalink / raw)
  To: 15547

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





^ permalink raw reply	[flat|nested] 4+ messages in thread

* bug#15547: 24.3.50; doc string of `isearch-cmds'
  2013-10-07  4:04 bug#15547: 24.3.50; doc string of `isearch-cmds' Drew Adams
  2013-10-07  4:55 ` Drew Adams
@ 2014-02-08  3:59 ` Lars Ingebrigtsen
  1 sibling, 0 replies; 4+ messages in thread
From: Lars Ingebrigtsen @ 2014-02-08  3:59 UTC (permalink / raw)
  To: Drew Adams; +Cc: 15547

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/





^ permalink raw reply	[flat|nested] 4+ messages in thread

* bug#15547: 24.3.50; doc string of `isearch-cmds'
  2013-10-07  4:55 ` Drew Adams
@ 2014-02-09  2:42   ` Drew Adams
  0 siblings, 0 replies; 4+ messages in thread
From: Drew Adams @ 2014-02-09  2:42 UTC (permalink / raw)
  To: 15547

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





^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2014-02-09  2:42 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2013-10-07  4:04 bug#15547: 24.3.50; doc string of `isearch-cmds' Drew Adams
2013-10-07  4:55 ` Drew Adams
2014-02-09  2:42   ` Drew Adams
2014-02-08  3:59 ` Lars Ingebrigtsen

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.