Subject: Re: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc.

From: Lars Magne Ingebrigtsen <[email-masked]>
Date: Fri, 15 Jul 2011 15:40:06 +0200

"Drew Adams" <[email-masked]> writes:

> 1. At a minimum, the doc string of `isearch-mode' should say something
> like this:
>
> FORWARD non-nil means forward search; nil means backward search.
> REGEXP t means regexp search; nil means literal search.
> OP-FUN means ???????
> RECURSIVE-EDIT non-nil means recursive edit for a modal search.
> WORD-P non-nil means word search; nil means ignore word boundaries.

It's an internal function.  If you're not an isearch hacker, you'll
never see it, and if you are, you will know what those parameters mean.
The only thing that's useful in that doc string is the thing that's
already there, and which you want removed:

> And you can remove this sentence from the doc string - a function's doc
> should, in general, not mention callers:
>
> "It is called by the function `isearch-forward' and other related
> functions."

> 2. Doc strings of `isearch-forward' etc. also need to describe their
> args.  E.g. 
>
> Non-interactively:
> REGEXP-P means...
> NO-RECURSIVE-EDIT means...

I think any reasonable person would guess that REGEXP-P means "it's a
regexp", and NO-RECURSIVE-EDIT means "we're not in a recursive edit".

So I'm closing this report.

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