[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

RE: Opaque objects and Emacs documentation

From: Drew Adams
Subject: RE: Opaque objects and Emacs documentation
Date: Fri, 17 Jul 2020 09:58:59 -0700 (PDT)

> Of course I did.  But as it happens, this difference does not exist in
> Emacs.  Remember that one of the direct inspirations of Emacs were Lisp
> machines, in which the user can read and modify almost every piece of
> code on the fly, from the lowest to the highest level.  In such a system,
> there can be no difference between "internal" and "external" documentation.
> I understand that it can be difficult to adapt to this way of thinking
> when one comes from another programming tradition.

FWIW, I agree.

The only uses of labeling something "internal" for Emacs
are (1) to indicate some relative risk/expectation of
future change in implementation and (2) to indicate some
relative risk in changing some fragile or tricky code.

And even in those case, IMO just a binary label "internal"
vs "external" is not the way to go.  Just document in more
words what's involved - which kind of risk, maybe exactly
what the risks are or the future expectations/intentions

IOW, "relative" is key here - it's not about an unexplained
absolute "hands-off" or "don't look".  We aren't limited
to just hanging an "Off Limits - No Admittance" sign.  We
can tell our future selves just what's involved, and why.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]