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

Previous Next

Full log

View this message in rfc822 format

From: Juanma Barranquero <lekktu <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Lars Magne Ingebrigtsen <larsi <at> gnus.org>, 8682 <at> debbugs.gnu.org
Subject: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc.
Date: Fri, 15 Jul 2011 18:56:07 +0200

On Fri, Jul 15, 2011 at 17:06, Drew Adams <drew.adams <at> 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

Previous Next

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