RE: Opaque objects and Emacs documentation

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

FWIW, since the question was asked -

I'm in favor of documenting pretty much all
Emacs-Lisp functions and variables _all the way
down_.

(Even lambda expressions sometimes deserve a doc
string.  And yes, a comment can also serve, but
a doc string is generally better for describing
what something is or does.  A comment is generally
good for describing design decisions or unobvious
code considerations.)

And this is so whether or not someone considers
this or that particular thing to be "internal",
whether just for now or for all time.

If you write code for yourself, any designation
of "internal" is just a note to yourself that
either (a) the code in question is asking to be
revisited and possibly changed later, perhaps
including its interfaces with other code, or (b)
the code in question is tricky or fragile, so
fiddling with it can be asking for trouble.

With free software, all code we write is code
for ourselves, because ourselves includes
everyone, now or later.  This means that all
labeling of "internal" is only a comment saying
(a) or (b), above.

Such labeling is _never_ a reason, with free
software, _not_ to describe something.  We're
not (should not be) trying to hide anything
from anyone, including ourselves.

There's too much labeling of stuff in Emacs as
"internal", IMO, and this has increased over
time.  For the most part it's not necessary or
useful.

Too often, I think, such branding as "internal"
is really a cop-out from someone who isn't
interested in the doc/help, or doesn't want to
take the time to describe things (e.g. in
English), or has trouble doing so, or just has
a mental "block" about doing so (similar to
math phobia), or even is unsure of the thing
to be described and wants to save the possible
embarrassment of offering an off-the-mark
description.  Such "feeling" motivations do
happen sometimes.

Such feelings can be understandable, but they
are never a reason why the things in question
_shouldn't_ be described.  They can be reasons
why the person having such feelings shouldn't
need to be the one to document those things.
They're just not a reason why things shouldn't
be documented at all.

The case of generated functions and variables
is a special one.  Generic functions are one
example of creating things programmatically.
`cl-defstruct' is another example.  Even things
like `define-minor-mode' are examples.

In these cases we need to (should, IMO) find
ways to:

1. Programmatically add _some_ useful doc, when
   feasible.  We've done that for things like
   `define-minor-mode', but there's still room
   for improvement.

2. Provide ways for the programmatically added
   doc to be manually tweaked (supplemented,
   replaced).

3. Actually _do_ such manual tweaking.  And
   to the extent that we haven't provided
   good solutions for #1 and #2, just provide
   the doc manually, whenever possible.

Lisp is not your average language.  And free
software doesn't have the same constraints
and purposes as proprietary software.  _Some_
of the typical encapsulation and rendering of
things as opaque/internal is motivated by a
spirit of protection of property/control that
doesn't apply to free software.

The point is not to not have abstractions or
use macros or higher-order functions.  It's
not to _force_ someone to dive deep for
understanding.  The point is to provide help
all the way up and down.  There's no good
reason _not_ to do that, IMO.

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

Just one opinion.  And thanks for posing the
question, Eli.