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: Fri, 10 Jul 2020 17:57:12 +0300
> 
> 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.

We could add something to find-file, like we do for VC-related files.

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

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

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

> >>     * 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?

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

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

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