bug#8101: 24.0.50; `isearch-search-fun-function'

bug#8101: 24.0.50; `isearch-search-fun-function'

[Drew Adams]

Doc string is broken:
 
"Override `isearch-search-fun'.
This function should return the search function for Isearch to use.
It will call this function with three arguments
as if it were `search-forward'."
 
First line is incorrect.  It overrides the default search function which
is used by `isearch-search-string', but it does not override
`isearch-search-fun'. It is *called* from `isearch-search-fun', so it
certainly cannot override it.
 
The biggest problem is the last sentence.  "It will call this function"
What is "IT"?  What is "THIS FUNCTION"?  And why mention
`search-forward' here?  Very confusing, if not downright incorrect.
 
Make it clear that this var's value is a function that is called with NO
ARGS and whose return value should be a function of the SAME THREE ARGS
as `isearch-search-string'.  That returned function will be used by
`isearch-search-string' to "search for the first occurrence of STRING or
its translation."
 
Further, the doc string of `isearch-search-fun' should also say that the
function returned accepts the same three args as `isearch-search-string'
- and so on.
 
In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-02-14 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags
-Ic:/imagesupport/include'
 

bug#8101: 24.0.50; `isearch-search-fun-function'

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> Make it clear that this var's value is a function that is called with NO
> ARGS and whose return value should be a function of the SAME THREE ARGS
> as `isearch-search-string'.  That returned function will be used by
> `isearch-search-string' to "search for the first occurrence of STRING or
> its translation."

I've clarified the doc string to the best of my ability now:

(defvar isearch-search-fun-function nil
  "Overrides the default `isearch-search-fun' behaviour.
This variable should be a function, which will be called with no
arguments, and should return a function that takes the same three
arguments as `isearch-search-string' requires.")

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

bug#8101: 24.0.50; `isearch-search-fun-function'

[Drew Adams]

> > Make it clear that this var's value is a function that is 
> > called with NO ARGS and whose return value should be a
> > function of the SAME THREE ARGS as `isearch-search-string'.
> > That returned function will be used by `isearch-search-string'
> > to "search for the first occurrence of STRING or
> > its translation."
> 
> I've clarified the doc string to the best of my ability now:
> 
> (defvar isearch-search-fun-function nil
>   "Overrides the default `isearch-search-fun' behaviour.
> This variable should be a function, which will be called with no
> arguments, and should return a function that takes the same three
> arguments as `isearch-search-string' requires.")

OK, but:

1. (English) "This variable's value should be..."  It is the value, not the
variable itself.

2. (Meaning) Without the last sentence I wrote above (or something equivalent)
we don't say what the function (value of the var) _does_.  What's the point of
someone providing a function as the value if we don't say what the function is
for?

bug#8101: 24.0.50; `isearch-search-fun-function'

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> OK, but:
>
> 1. (English) "This variable's value should be..."  It is the value, not the
> variable itself.
>
> 2. (Meaning) Without the last sentence I wrote above (or something equivalent)
> we don't say what the function (value of the var) _does_.  What's the point of
> someone providing a function as the value if we don't say what the function is
> for?

How about this version, which I've now checked in:

(defvar isearch-search-fun-function nil
  "Overrides the default `isearch-search-fun' behaviour.
This variable's value should be a function, which will be called
with no arguments, and should return a function that takes three
arguments: STRING, BOUND, and NOERROR.

This returned function will be used by `isearch-search-string' to
search for the first occurrence of STRING or its translation.")


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

bug#8101: 24.0.50; `isearch-search-fun-function'

[Drew Adams]

> How about this version, which I've now checked in:
> 
> (defvar isearch-search-fun-function nil
>   "Overrides the default `isearch-search-fun' behaviour.
> This variable's value should be a function, which will be called
> with no arguments, and should return a function that takes three
> arguments: STRING, BOUND, and NOERROR.
> 
> This returned function will be used by `isearch-search-string' to
> search for the first occurrence of STRING or its translation.")

Yes, thank you.