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

[Dmitry Gutov]

On 10.07.2020 17:27, Eli Zaretskii wrote:

> > In the same fashion that the author of bug#41029 arrived at the number
> > of ~6000 buffers (we could ask).
>
> 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.

> > I also worry about Tramp buffers, where both process invocations and
> > traversals up the directory tree are unavoidably slower.
>
> Once again, as long as a buffer's project is determined when the
> buffer is created

I have already explained that we don't do that. project is not a minor 
mode, and we don't waste CPU cycles determining each buffer's project 
eagerly.

Which is most likely a plus for Tramp, we don't need to make buffer 
opening even slower there.

> > > > Speaking of standards set by other editors, have you ever seen an IDE
> > > > with an "invalidate project cache" button? I haven't.
> > >
> > > I didn't say anything about a need for such a knob.  You are probably
> > > misinterpreting what I wrote above.
> >
> > All right.
> >
> > If you have suggestions of how we would reliably find outdated cached
> > values, please don't hesitate to tell.
> >
> > Examples of caches we could use:
> >
> >     * 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).

> > Does commit 4ca13d9 look good to you?
>
> Not really:
>
>    . 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?

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

Implementation-wise: same as the value returned by (project-current t) 
in the current buffer.

> So that commit looks like a step backwards to me.

Just because you don't like the new docstring?

That's harsh.

> (Also, the log message is in error (mentions the same function twice),
> but that's water under the bridge.)

Yes. Sorry. :-(