On Mon, Jul 13, 2020 at 07:11:21AM +0000, Gregory Heytings via Emacs development discussions. wrote:

[...]

> I might be wrong, but I think Dmitry's viewpoint is that if he
> documents X, then X becomes part of the API.  Other developers will
> (or might) use X in their code, and he would not be completely free
> to change X anymore [...]

Yes. But I think the core of the disagreement lies in *who*
decides where the line in the sand is. Dmitry seems to lean
to the side "the library designer does", while Eli to the one
"it's part of a collective process".

I'll leave this at that -- I'm aware that this is a huge issue,
and you'll find language designs more slanted to the one or to
the other direction, reflecting the one or the other culture.

Even the term "API", "application programming interface" conveys
the culture on the one side: here be the system programmers (better
paid, presumably), there be the application programmers. If one of
the latter *dares* to touch system things, (s)he's fired [1].

I wonder where the term "API" originated. I'd guess it comes from
the depth of the bowels of a 1960's to 1970's IBM, where you'd
have to apply for a variable name to a specialized department [2]. 

Cheers

[1] That was a bit tongue-in-cheek, and there *is* IMO a valid
   case for "separation of concerns", I do it all the time with
   myself. I just wanted to raise the contrast a bit.

[2] Again, lots of tongue-in-cheek and a barrel of salt apply.
   That thing with a variable name is from memory and might
   be grossly misremembered.

-- t