GNU bug report logs - #8682
24.0.50; doc strings of `isearch-mode', `isearch-forward', etc.

Previous Next

Full log

Message #24 received at 8682 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 8682 <at> debbugs.gnu.org
Subject: Re: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc.
Date: Fri, 15 Jul 2011 15:40:06 +0200

"Drew Adams" <drew.adams <at> oracle.com> 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/

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.