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

[Eli Zaretskii <eliz@gnu.org>]

> Cc: theo@thornhill.no, philip@warpmail.net, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 12 Jul 2020 17:16:19 +0300
> 
> If I said something is a bad idea, don't go ahead and ignore me. This is 
> extremely rude.

This goes both ways.

> Not documenting internal information is a valid choice.

It isn't internal.  Anyone who wants to use the return value will need
to understand its possible form(s).

> > But other than that, if someone needs to write code for the VC project
> > backend, how can they NOT rely on the form of the object that
> > project-try-vc returns?
> 
> Nobody should "write code for the VC project backend" except its 
> author(s).

This is a community project, and everybody is welcome to contribute
code to any part of Emacs.  Restricting some parts of code to a single
person is not a good way of ensuring Emacs's future.

> Whatever fuctionality users need to implement, should target the open 
> API. Which does not depend on the shape of the return value of 
> project-try-vc.

With respect, I disagree, having read the code and having considered
how I would implement something related to it.  That is the single
most important reason why I'm trying to improve the documentation of
this package: to make it easier for others to expand and extend it.

> > Why should that form, which is important for
> > handling any VC project, and is thus part of a public API, be left
> > undocumented?
> 
> No, they can't. That information can freely change between versions, so 
> any reliance on it will create compatibility problems when upgrading.

Then let's say that.  But concealing the information will not solve
the problem, because you cannot conceal it.  By not mentioning it and
the caveats to go with it we will be punished twice: we will make it
harder for people to understand the current code and contribute to it,
and we will not make sure they realize that relying on these details
is not a good idea.

> > You anyway cannot conceal from users information about the innards of
> > a Lisp implementation: since the source code is there for everyone to
> > see and study, any information you try to conceal will be eventually
> > found.  All you can do is cause users aggravation by forcing them to
> > hunt for that information through many rabbit holes.  There are no
> > advantages to doing this, only disadvantages.
> 
> If my method of saying "don't rely on this format" is insufficient, 
> please go ahead and add some more clarifications on that part. But 
> without documenting this said value format.

You cannot usefully tell people to not rely on something without
describing that something.  And there's the other disadvantage to
concealing information: obfuscation of the code.

> > More generally, please put yourself in the shoes of someone who wants
> > to extend an existing backend, or add a new backend, and try to read
> > the documentation through their eyes.
> 
> If they create a new backend, they will read the code of the existing 
> one.

That's not how we encourage extending Emacs.  Some minimal
documentation is needed before we can in good faith tell users to read
the code, and project.el currently falls short of that minimum, IMO.

> > They will need to know
> > something about the methods they should implement/extend, about which
> > ones are and which ones aren't mandatory.
> 
> That is orthogonal to this issue.

I don't think it's orthogonal, I think it's all part of the same
issue.

> > They will need to know
> > something about what the project object is or can be, and what minimum
> > capabilities should it have.
> 
> Hence the description in my latest commit.

It was insufficient.  And what we have now, after my changes, is still
insufficient, IMO.  More work is needed.

> >> We have enough trouble with user-defined functions returning (cons 'transient some-root-dir) already.
> > 
> > Which trouble is that?
> 
> People try to customize the root-finding logic this way, and as a result 
> get a project backend that behaves more slowly than the VC one. And that 
> affects all of project-* commands that they might like to use.

People learn by doing and by making mistakes.  It is not a catastrophe
if their first attempt is suboptimal.  Making the documentation better
might be one way of helping them understand how to DTRT.

> > And as long as we are talking about this: you mentioned the
> > "transient" project without defining what it is.  That is not useful.
> > I tried to add some minimal explanation of that, and also fixed
> > another related omission.
> 
> I would say thank you, but you again documented the return value there.

Of course.  It's a value that others need to be aware of.

> The value is *irrelevant*, and it is, again, internal to the backend.

Which backend is that?  AFAICT, project-current is backend-agnostic.