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

["Drew Adams" <drew.adams@oracle.com>]

Reopening.  None of the issues raised in the bug report have been addressed.
The thread was simply side-tracked by Stefan concentrating on suggested
parameter names.  Then along comes Lars and just closes the bug, apparently not
reading the report or paying no attention to what it says.

The bug report is not about the parameter names used - there were only
parenthetical remarks about the names.  Call the parameters whatever you like.

The bug is about undocumented parameters, poorly documented parameters,
inappropriate statements about calling functions, missing doc, and inadequate
doc.  Please read the report.  This should be a no-brainer.  I even suggested
text for some of the individual parameter descriptions.

Doc for a function needs to describe its parameters and say what it does.  In
many cases it also needs to describe the return value.  There is nothing new
about this.

> 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.
>  
> 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."
 
> OP-FUN: It corresponds to `isearch-op-fun', but there is no doc
> string for `isearch-op-fun', and the accompanying source comment 
> does not help - it says only when `isearch-op-fun' is called, not
> what it is for or how it is used.

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


> 3. More generally, isearch.el needs more and better doc strings.