[Top][All Lists]

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

Re: Opaque objects and Emacs documentation

From: Gregory Heytings
Subject: Re: Opaque objects and Emacs documentation
Date: Fri, 17 Jul 2020 11:53:22 +0000
User-agent: Alpine 2.21 (NEB 202 2017-01-01)

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.


reply via email to

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