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

[Dmitry Gutov]

On 10.07.2020 21:14, Eli Zaretskii wrote:

> > > Please do ask, because I don't see how could hundreds of buffers
> > > belong to a project without being created by commands that know about
> > > the project.
> >
> > They can open a bunch of files that reside in a project's directory
> > (roughly speaking; if the project backend is directory-based). You don't
> > need a command named project-* to do that.
>
> We could add something to find-file, like we do for VC-related files.

I mean, yeah. We could. That would be one way to cache (eagerly). Then 
whatever operation that created those 6000 buffers would pay the price.

> Maybe we should waste those CPU cycles, so that they don't add up.

I'm inclined to say "no" (Tramp is slow enough). But that's a secondary 
decision.

Whether we do cache eagerly (by wasting said CPU cycles in advance), or 
save per-buffer "current project" value on demand, either way that would 
mean caching it.

And either way, that brings up the issue of cache invalidation.

> > Which is most likely a plus for Tramp, we don't need to make buffer
> > opening even slower there.
>
> We could have a defcustom to disable that for those who will seldom
> if ever use project.el.  And again, we do that for VC.

Tramp has extra-special handling for VC. It probably wouldn't be able to 
do that for all possible project backends.

> > > >      * file or directory -> project
> > > >      * project -> list of files
> > >
> > > These should be updated when the file is added to a project or removed
> > > from it.  Or maybe I don't see the difficulties you have in mind.
> >
> > File can be added to a project in a multitude of different ways. By
> > using Vim in a terminal, for instance. Or the 'touch' command.
> >
> > Removal also happens through different venues (removal in Dired, on 'rm'
> > in the terminal, or changing the project configuration to ignore the
> > said file).
>
> Why should we care about adding or removing a file that are not
> visited in Emacs?

A file already opened in Emacs might be added to some project this way 
(by editing project config, or doing 'git init'). Then, ideally, two 
things need to happen:

- The "current project" cache of said buffer (if it is already visited) 
needs to be invalidated.
- The "project-files" cache (currently not cached) of said project needs 
to be invalidated as well.

When a file is removed from project, the latter needs to happen.

> > >     . it makes the doc string of project-switch-to-buffer intentionally
> > >       obfuscated by "explaining" stuff in terms of the implementation,
> > >       which makes it not very useful (as I already tried to explain in
> > >       the past)
> >
> > What are you suggesting?
>
> Explain what project-current does, most probably, right in that doc
> string.

project-current finds the current project of the buffer. Or the project 
to which the current buffer is related. Would that explanation make 
things better?

The exact logic of project-current depends on the configuration of 
project-find-functions.

> > >     . the new doc string is confusing: "if 'project-current' returns the
> > >       same (equal) value" is incomplete, because it doesn't say the same
> > >       as what
> >
> > Same as the current project value, if any (otherwise, same as the value
> > returned by the project selection prompt).
>
> Please fix the sentence, then.

I'll do my best.

> > > So that commit looks like a step backwards to me.
> >
> > Just because you don't like the new docstring?
> >
> > That's harsh.
>
> I didn't see any other significant changes, sorry.

You asked for the buffer-matching logic not to depend on 
default-directory anymore. It doesn't.

Now project-switch-to-buffer and project-kill-buffers should work with 
Stephen's backend, as well as any "manually managed project" backend you 
might choose to write.