Re: Opaque objects and Emacs documentation

[Dmitry Gutov]

On 17.07.2020 14:53, Gregory Heytings via Emacs development discussions. 
wrote:

> 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?

> 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.

Even coming back to it in a few years, I'm pretty sure I can spare 
several seconds to call project-try-vc and see which value it returns.

The most valuable documentation is not this kind:

  // add 1 to x
  x += 1

but 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.