Re: Opaque objects and Emacs documentation

[Dmitry Gutov]

On 17.07.2020 17:26, Gregory Heytings via Emacs development discussions. 
wrote:
> Of course I did.  But as it happens, this difference does not exist in 
> Emacs.  Remember that one of the direct inspirations of Emacs were Lisp 
> machines, in which the user can read and modify almost every piece of 
> code on the fly, from the lowest to the highest level.  In such a 
> system, there can be no difference between "internal" and "external" 
> documentation.

Why not?

Given that Lisp allows one to expect any value, and jump to any 
implementation, and debug any function, I would say that actually 
_lowers_ the need to document things, in general, not the other way 
around, like in environments which you can't inspect and thus have to 
rely solely on documentation.

As for internal vs external difference, I believe it's still here, as 
with any programming language. The latter should be much shorter. There 
is no need to dump all internal details on somebody who just wants to 
use a library. It's simply counter-productive.