[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Dmitry Gutov
Subject: Re: master 1e3b0f2: Improve doc strings of project.el
Date: Sun, 12 Jul 2020 17:16:19 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0

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

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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]