[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Opaque objects and Emacs documentation

From: Dmitry Gutov
Subject: Re: Opaque objects and Emacs documentation
Date: Fri, 17 Jul 2020 16:13:33 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0

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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]