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

[Gregory Heytings]

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

Gregory