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

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

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?  Why should that form, which is important for
handling any VC project, and is thus part of a public API, be left
undocumented?

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.

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.  They will need to know
something about the methods they should implement/extend, about which
ones are and which ones aren't mandatory.  They will need to know
something about what the project object is or can be, and what minimum
capabilities should it have.  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.  And on top of that you
insist on removing details from the documentation that _is_ available.
This makes documentation worse, not better.

> We have enough trouble with user-defined functions returning (cons 'transient some-root-dir) already.

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

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.

Thanks.