[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: Mon, 13 Jul 2020 04:51:33 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0

On 12.07.2020 19:17, Eli Zaretskii wrote:

Can we approach this from a different angle, please?  Can you tell why
you are so opposed to having this small piece of information in the
doc strings?  What harm can it do that you consider unacceptable?

Let's try this again.

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.

Here are things we want third-party code to be able to do:

- Consume the public project APIs, which are currently limited to 'project-current' and several generic functions defined for project instance values, to define new commands or supplement existing ones (e.g. to query the current project for its root or its list of files).

- Create new project backends. Note that we don't want *everybody* to do that because creating a well-performing backend is a significant amount of work (unless the user has very particular needs and works with small projects). But we want this to be a solid option, and it would be ideal if, say, a handful of backends become popular someday. To create a backend, one needs to choose the format of its instance value (which shouldn't match any of the existing formats), write its project-find-functions element, and define the project-root override that dispatches on its instance value. Preferably, also implement overrides for project-ignores and project-files.

Neither of these options requires knowing the exact format of project-try-vc's return value, if only to stay away from it. But the odds of a collision seem very low (and there are ways to reduce them even further).

Here are, on the other hand, things that people generally shouldn't do, and yet I have seen them done:

- Extract data from the project instance value directly, instead of going through e.g. 'project-root'. For instance, writing (cdr (project-current t)) instead of (project-root (project-current t)). The former is bad code.

- Write a new project-find-functions element which returns an instance value that belongs to a built-in backend (usually, the 'transient' one). AFAICT, this is usually done by cargo culting, without understanding of the consequences.

Both of these require knowing the exact value formats of project instances used by built-in backends. Thus, documenting them will encourage these usages.

I don't want to prohibit the last option outright, but we shouldn't leave any impression that it's legitimate either. And most problems that people try to solve this way (predominantly: customizing project root markers, AFAIK) should be filed as bug reports/feature requests.

I added that piece of information because without it I couldn't wrap
my head around what the code does, in particular when it tries to
determine which projects are equal to which.

But it's the wrong direction.

I mean, you *can* look at the shape of the instance returned by project-try-vc (which is trivial to do: evaluate the form (project-current t) and look at the echo area), but it doesn't give you any guarantee: after all, we need to make sure project-switch-to-buffer's behavior makes sense for different backends, even ones we didn't write.

So documenting that one backend's instance format is not a solution.

Instead, it seems we have to document that said value should uniquely identify the returned project and be "stable": not change over time or when fetched from different buffers belonging to the same project. That also means that the value shouldn't contain any caches inside of it.

And once we add these requirements, the answer to "which projects are equal" translates to:

- The backend is the same,
- The instances describe the same project, but the exact fashion depends on the backend. As it would be anyway.

I reckon if this was
difficult for me, there will be others who could benefit from having
that info.
This kind of internal information might be better suited for code comments. I'm not sure where you could put this particular bit of information, where it would both be relevant and yet not obvious from the nearby code, though.

reply via email to

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