[Top][All Lists]

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

Re: master 1e3b0f2: Improve doc strings of project.el

From: Gregory Heytings
Subject: Re: master 1e3b0f2: Improve doc strings of project.el
Date: Mon, 13 Jul 2020 07:11:21 +0000
User-agent: Alpine 2.21 (NEB 202 2017-01-01)

This information is private (or "internal") similar to when we designate variables or function private: we don't want people to rely on it because a) that might lead to wrong decisions, b) that might lead to breakage because this information is subject to changing at will. For example, I'm considering turning the whole value into a list (it's currently a shallow cons) and adding the VC backend symbol to the project-try-vc's return value as the second element to save some CPU cycles.

When the form of the return value changes, we will update the documentation. This kind of thing happens all the time in Emacs development, and is nothing to be afraid of. Especially if you consider some information "private", which means we under no obligation to preserve its form. We even have an "Internals" chapter in the ELisp manual (woefully incomplete, but not because we decided not to tell those missing details).

This is why I'm frankly astonished by your opposition to document the return value. Once again: what's the catastrophe in doing that?

I might be wrong, but I think Dmitry's viewpoint is that if he documents X, then X becomes part of the API. Other developers will (or might) use X in their code, and he would not be completely free to change X anymore. He would have to keep X in a number of future versions of his code, document X as being obsolete for a while, create Y in parallel, and only later remove X from his code.

IOW, it is not only a matter of updating the documentation, it is a matter of updating all code that relied on that documentation.

(Note that this does NOT mean I agree with Dmitry.)


reply via email to

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