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

[Eli Zaretskii]

On July 13, 2020 10:11:21 AM GMT+03:00, "Gregory Heytings via Emacs development 
discussions." <emacs-devel@gnu.org> wrote:
> 
> >
> >> 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.


I tried to explain why these fears have no basis: if we clearly say that some 
details are subject to change without notice, we can change them when we need 
to.

IOW, doing that does NOT make these details part of the public API which we 
promise shall remain stable.