Re: Opaque objects and Emacs documentation

[Gregory Heytings]

> > IMO the main goal of writing Emacs documentation (and software 
> > documentation in general) is not to help its users, but to help all 
> > those who in the future, when you will have moved to something else, 
> > will work on the code you wrote.
>
> So you have never encountered a difference between internal 
> documentation and public documentation?

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.  I 
understand that it can be difficult to adapt to this way of thinking when 
one comes from another programming tradition.

> The most valuable documentation is [...] that which describes original 
> choices, and the reasons for them. Or an overview of how the system 
> works. We're not discussing either of those options here.

It's one way to document things, but certainly not the only one.  I'm not 
sure I agree that it's the "most valuable" one.  When you have to work on 
code written by someone else, you rarely do so on the highest level, and 
having a picture of the overall organization is not directly useful. 
Having a clear and well-written documentation for each function is 
directly useful.

Gregory