Re: Opaque objects and Emacs documentation

[Gregory Heytings via "Emacs development discussions." <emacs-devel@gnu.org>]

>
>> Which I think is against long-time Emacs tradition for documenting its 
>> interfaces, and by that facilitating extensibility.  It is IMO wrong to 
>> fill Emacs application levels with opaque objects which cannot be 
>> usefully described; they should be a rare exception, but definitely not 
>> the rule.
>
> The problem here is that even if you document a particular value, it's 
> _not useful_. It doesn't show you what you can or should do with it.
>
> The main thing thing the user can do with that value is misuse it, by 
> relying on its shape in the client code.
>

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.  For them it is definitely very useful to 
understand the implementation choices you made, the internal 
representations you chose to use, and so forth.  In fact, such a 
documentation is probably also useful for yourself, if you leave your code 
temporarily, and come back to it after a while.

Gregory