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

[Juanma Barranquero]

On Fri, Jul 15, 2011 at 17:06, Drew Adams <drew.adams@oracle.com> wrote:

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

Of course there are internal elisp functions. Many of them even use a
convention of having two consecutive dashes in the name to mark that
they are internal, but not all.

And what makes them internal is that they are an implementation detail
and could be removed, or changed beyond all recognition, at any
moment. Documenting them past the simple "This is an internal
function" leads the user-developer to falsely believe that they are
part of the interface, but they are not. Otherwise, nothing could ever
be changed but painstakingly and with lot of ugly compatibility code.
Which is fine for the advertised interfaces, but not for every single
function in every single package in lisp/**/*.el.

First someone asks to document them all, then s/he will use them in
some package, and finally s/he will complain harshly when they are
deleted in some future release. Better to say clearly: don't do that,
or do it under you own responsability, after looking at the code, and
knowing full well that if you do you'll likely need to workaround
changes in the future.

(I'm not talking about the specific changes in this bug thread, but
comments like "Nothing in Emacs is truly 'internal'" cannot be let
pass unchallenged...)

    Juanma