> > The built-in help and thorough-going introspection of
> > Emacs and Elisp are in fact outgrowths from Lisp and
> > the Lisp community.  Lisp has had this strength from
> > the outset.
> 
> I don't know about the various forms of introspection, but at AFAIK
> (none of this is 100% sure, sadly) in the specific case of docstrings,
> this comes from TECO and I believe it was added to TECO by Richard
> while working on the TECO version of Emacs.

Yes, but RMS was embedded in a culture of Lisp.  The
editor used at MIT then was TECO.  And unlike Interlisp
the MacLisp environment used editing etc. tools that
were outside Lisp itself.  The "open" approach to
editing, and to help in code editing, came from the use
(practice) of Lisp: interactive, live modification of code.

> > And RMS has always had a strong will to keep Emacs open and
> > self-aware/self-documenting.  "Doc", in multiple senses, 
> > has always been important to Emacs.
> 
> While the GPL doesn't say anything about it, it's clear that's an
> important part of empowering users, so it's closely linked to the
> ideals of Free Software.

Yes.

> [ In a sense, the source code of a program is a kind of documentation
>   of the corresponding assembly generated by the compiler. ]

Yes.  Even so, there's been no tendency in Emacs to
skimp on providing good doc and code comments.  IOW,
the availability of the source code isn't taken as an
excuse to not improve transparency by supplementing
code with doc.

> > Unfortunately, there's been more of a tendency in
> > recent years to "name-claim" more things to be
> > "internal", as if that somehow protected something or
> > someone (Emacs development/developers? Elisp users?).
> 
> Note the strong difference between the "--" naming convention to
> announce a function/var is internal, with the use of strong language
> abstraction to make internal inaccessible.

Yes, of course.  That's at least in the right direction.

And of course there's the even stronger difference
between providing source code and withholding it.  It's
about transparency and intentionally fostering it.

> Emacs is not in the business of preventing users from shooting
> themselves in the foot, but we do try to make it easier for the users
> not to shoot themselves in the foot, which is why we like to document
> with "--" when a function is intended to be internal.

Black-&-white.  Users are developers of Emacs, and its
developers are users.

Intention to be internal, as a _Note to (communal) self_
that XYZ might be fragile, or might need to change soon,
or has this limitation, or whatever, is better written
out specifically in comments or doc - saying why, in
what ways, under what conditions, etc.  Specifics,
reasons - think it out and express it explicitly.
Don't just label: `--'.

Just labeling something "internal" can do as much harm
as good (or more).  It's too easy to do and forget.
It takes no responsibility for communicating what's
going on - what's _behind_ the intention/judgment.
It's a crutchy, misleading label, at best (and worst)
providing (whom?) a false sense of security.

It essentially belies a perceived or intended/wished
separation between users ("lusers") and developers.
And that's a separation that free software ultimately
explodes, intentionally, explicitly, forthrightly.

At the very least, every use of `--' should have an
easily findable comment or doc, explaining what it's
about - why the labeler labeled it so.  A guess is
that if that guideline were adopted there'd be a lot
less gratuitous use (misuse) of `--'.  And updating
out-of-date `--' would be less problematic.  Today,
it's an irresponsible, easy "label `--' willy nilly,
and forget about it."
___

Just one opinion...