RE: Opaque objects and Emacs documentation

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

> > "Don't look! - INTERNAL" is, in particular,
> > not a good reason.  It's not a reason at all,
> > except perhaps in the context of protecting
> > private property, which we're not in the
> > business of doing, here.  Opaqueness should
> > be anathema to free software.
> 
> "You may look, but try not to touch" would perhaps be a better analogy.

Fine.  And a comment as to why is a plus.

> Lisp indeed is a special language, and any concerns that my choice
> would actually be _hiding_ something from the users is a dramatic
> overstatement. Both the code and the returned values are trivial to
> examine.

My post didn't speak about your choice for anything.
It's not about you.  I replied to Eli's request for
input on the general question.  An interesting and
useful question, IMO.

A general comment on your reply, here, is that the
trivialness of code and return values can be in the
eye of the reader.

And accompanying description rarely _hurts_.

It hurts when it's _wrong_ or misleading, and in
that case, especially if written by the code author,
such inaccuracy can be a sign that something isn't
understood as well as it should be.

That's another purpose doc/description serves: it
can be a check on our understanding.  This is one
of the reasons for careful _specifying_, whether
for requirements, design, tests, whatever.