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

[Dmitry Gutov]

On 19.06.2020 18:11, Eli Zaretskii wrote:

> >   >>>      Switch to another buffer related to the current project.
> >   >>>    A buffer is related to a project if its `default-directory'
> >   >>>    is inside the directory hierarchy of the project's root.
> >   >>
> >   >> Sounds good. Except some projects can be inside one another, too.
> >
> >   > Does that invalidate what the text above says?
> >
> > 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.

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

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. And there are also 
derived compilation modes, which pertain to specific projects even more 
(e.g. they contain test runner outputs).

> and a simple "C-x b" should be enough to switch to
> them.

'C-x b' can be used in a lot of cases, but what I have seen requested 
here, it being able to do all work on a project (or as much as possible) 
while only using 'C-x p b'. It makes some sense to me, and I think 
Projectile has proven the demand for such command.

> project-switch-to-buffer should be more helpful by offering
> only "useful" buffers.

That is indeed an option, but Andrii requested a different behavior. 
Please see the original discussion.

> > Also, different projects can have files with conflicting names.
>
> That cannot be solved by completion, where only the basename is
> usually shown.

It can, if we ask Emacs to only show the buffers from the current 
project. Then you don't need to worry about conflicting with other projects.