RE: Opaque objects and Emacs documentation

[Drew Adams]

> ... looking for ways to build and compose ever better
> abstractions.  Sometimes that has taken the form of
> adopting a new programming language, sometimes a new
> methodology or disciple.

> ... one of the banes of my existence has been leaky
> abstractions.  For better or worse, based main[ly] on
> the untyped nature of lisp and its culture of
> describing how to interpret structures of various
> shapes, my overriding impression of the lisp world in
> general and of elisp in particular is that they are
> rife with leaky abstractions.

FWIW, I can sympathize with that.  I don't think anyone
is arguing for less abstraction or in favor of leaky
abstractions.  And I agree about the problems you cite.

Lisp is not Haskell, for sure.  It does provide constructs
for building abstractions, notably higher-order functions
and Lisp macros.  But because it's imperative/procedural,
and in particular it's used/intended for operating on code
as data, it's less amenable to declarative specification
and static reasoning.

Practical Lisp (as opposed to a purely functional Lisp)
is a dynamic language that lets you reach all the way down
to bits and active procedures, including ones that are
doing the reaching.  It lets you examine your own guts,
and even operate on them without anesthesia.  Yikes!

For better and worse, that's Lisp.

> I commend Dmitry's desire to provide an opaque
> abstraction for a project.

I have nothing to say about that particular attempt or
that particular project.  My comments are about the
general question of documenting code, for both users
and developers.

But again, I think the abstraction / no-abstraction
argument is a false dichotomy here.