RE: Opaque objects and Emacs documentation

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

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

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.