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

[Drew Adams]

> It's an internal function.

"Internal" functions too deserve doc strings, in general.

And nothing in Emacs is truly "internal".  Emacs purposefully documents itself,
at all levels.  That documentation is available to all users interactively.

Skip creating reasonable doc strings and you stab Emacs, the "self-documenting
editor", in the back.

It was only in the Dark Ages, when doc strings were expensive because hardware
was expensive, that we used comments instead of doc strings for many "internal"
functions.

We should not be lazy and cop out wrt "internal" functions.  There is no strict
separation in Emacs (or GNU generally) between users and developers, between
"internal" code and external use of that code.

> 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."

No, that is not "useful".  More importantly, it is generally a bad idea for a
callee to call out who calls it.  There are exceptional cases, but this is not
one.