Subject: bug#35498: 26.2; doc string of `isearch-regexp-function'

From: Drew Adams <[email-masked]>
Date: Fri, 3 May 2019 07:47:57 -0700 (PDT)

> > The doc string should describe the possible values and their
> > meanings/behaviors.  Currently it describes only a function as value.
> 
> I added the existing functions that could be used as values.  Their
> descriptions are available by using the hyperlink, so no need to
> duplicate that here.  The list is, of course, not exhaustive, as Lisp
> programs could define their own functions.

It should instead, or in addition, specify what args it
must accept and what kind of value it must return.
Examples are only nice-to-have, not a replacement for a
description/spec.

> > Searching isearch.el it seems that this variable can be any of the
> > values possible for `search-default-mode'.  Please describe each of the
> > values for `isearch-regexp-function'.
> 
> See above: not needed.

The doc string should say that the value can be t, nil,
or a function. It should say what the behavior is for
each.  Or, as I suggested, it can just say that the
value can be anything acceptable for `search-default-mode'. 

> > Even when the value is a function the description could be better,
> > saying that it must accept a string as its first arg and must return a
> > string.  That can be surmised from saying that it converts a plain
> > search string to a regexp [search string], but it could be clearer.
> 
> Added.

OK, good.  That cancels what I said first, above.  I
thought you were saying that it is sufficient to just
give a list of existing such function values.