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

[Dmitry Gutov]

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.