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

[Eli Zaretskii <eliz@gnu.org>]

> Cc: theo@thornhill.no, philip@warpmail.net, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Fri, 19 Jun 2020 21:33:34 +0300
> 
> >> If the current project contains a few other projects inside of its
> >> subdirectories, project-switch-to-buffer probably should offer any of
> >> "their" buffers for switching.
> > 
> > "Should" or "should not"?  If the former, then the text I proposed is
> > fine as it is.
> 
> Sorry, should not.
> 
> But it's an edge case. So we could take your description now. But we'd 
> need to change it when/if that edge case is fixed. The fix isn't 
> difficult, I'm just unsure about its performance characteristics.

I'm not sure that the doc string will have to be changed (or how) when
you fix that, but that's a separate issue.

> >> As soon as you start relying on completion hints, you don't need to
> >> remember the names in advance. And it's also a good overview of the
> >> current open buffers in the current project.
> > 
> > If this is just for completion's sake, then I could understand, but
> > still it sounds very strange to include stuff like *XREF*, Eshell,
> > Occur, *Compilation*, *Grep*, etc.  Those are basically singletons, at
> > least by default,
> 
> Not really. In most of these cases, such a buffer shows results 
> pertaining to a specific project, so its contents are basically 
> irrelevant when a user is working on a different one.

But the default-directory of these buffers is a very weak evidence of
them being relevant to some project.  E.g., I could (and many times
do) grep some other project when I need to see how it solves some
problem which is relevant to what I'm working on now.  If we really
want to record in these buffers what project they are related to, we
need to have stronger evidence, like what was the current-buffer when
the command was invoked, or maybe something else (like name the
buffers in some special way).

> Occur can be an exception because multi-occur can work across buffer 
> (and thus, projects). Help buffers contain history, so they are special 
> too. But the rest usually fall in with that rule.

"The rest" are a legion.  I suspect that many/most of them are like
Occur and Help.  We should audit them before we make such far-reaching
conclusions (unless someone already did).

> > project-switch-to-buffer should be more helpful by offering
> > only "useful" buffers.
> 
> That is indeed an option, but Andrii requested a different behavior. 

That's fine, but Andrii's opinion is not the only one that counts, is
it?  We are talking about a general-purpose Emacs feature, not about a
command that will only be used by a single person.  It should make
sense to all of us.