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

[Eli Zaretskii]

> Cc: theo@thornhill.no, philip@warpmail.net, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Tue, 7 Jul 2020 18:23:17 +0300
> 
> On 07.07.2020 18:04, Eli Zaretskii wrote:
> 
> >> That would still potentially leave hundreds of buffers in which said
> >> commands have never been used.
> > 
> > I don't see how this would happen.  But we can cross that bridge if we
> > ever get to it.
> 
> 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.

> 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 don't think we need to worry about this.

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

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

  . 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

So that commit looks like a step backwards to me.

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