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

[Dmitry Gutov]

On 12.07.2020 17:00, Eli Zaretskii wrote:
> > Cc: theo@thornhill.no, philip@warpmail.net, emacs-devel@gnu.org
> > From: Dmitry Gutov <dgutov@yandex.ru>
> > Date: Sun, 12 Jul 2020 03:48:52 +0300
> >
> > I've scaled back the explicitness a little:
>
> I've added back the information you removed.  I think the removal was
> a mistake, as explained below.

And you were asking why I "interpret what you are saying in the worst 
possible way"? You're behaving like an autocrat.

If I said something is a bad idea, don't go ahead and ignore me. This is 
extremely rude.

> > we don't need people to rely on (or try to replicate) the exact format of what 
> > project-try-vc returns.
>
> This is a reason to have _more_ documentation, not _less_.  E.g., if
> you want the users not to assume or do something, say that explicitly
> in the documentation.  Or add some other information which will make
> it abundantly clear that relying on some detail is a bad idea.

Not documenting internal information is a valid choice.

> 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). And this backend is maintained strictly within project.el.

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.

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

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

> 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. They're free to copy, but they won't be bitten in the ass when the 
format changes, because their copy will not.

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

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

> The documentation in project.el
> currently has very little to say about this.  Various crucial details,
> like how project instances are compared, are never really explained,
> and only become evident from reading the code.
Some extra guidance can be helpful. That doesn't mean your particular 
choice is the best one.

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

> Is it possible that this trouble was caused by
> not documenting enough about project.el interfaces and objects?

Perhaps. It's undoubtedly (as everywhere) both a documentation and user 
comprehension problem. I've tried to improve the docs.

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

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