bug#13923: 24.3.50; doc strings of Isearch commands

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

> > The doc strings of `isearch-forward' etc. should describe 
> > each of the arguments.  That includes arg NO-RECURSIVE-EDIT.
> > This applies to all Isearch commands.
> 
> The docstring of `isearch-forward' describes the whole 
> Isearch facility for interactive use with all its available
> commands and keys.

On its own, irrelevant.

If you expect someone looking at the doc string for function `foo' to go to the
doc string of function `bar' to get part of `foo's description, then provide a
link from foo's doc to bar's, and make clear that the parameters correspond etc.

>  If this function is called non-interactively, it does not 
>  return to the calling function until the search is done.
> 
> that describes the effect of NO-RECURSIVE-EDIT.

Does it say that that is a description of NO-RECURSIVE-EDIT?  No.

If that is what the intention is, please make the connection, explicitly, so
user's do not have to guess that that is what you mean.

A user should be able to scan or search the doc string for a parameter name, to
find its description (especially when the doc string is long, as in this case).

> > The doc string of `isearch-mode', especially, needs to 
> > describe each of its arguments.  It currently describes
> > none of them.
> 
> This is described already in the Commentary section of isearch.el:

Irrelevant.  Which part of "doc string" is not clear?  By "self-documenting
editor", Emacs does not mean only that you can find some comments that might
help in the source code.  Emacs promises more than that.