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

[Dmitry Gutov]

On 20.06.2020 15:32, Eli Zaretskii wrote:

> > On 20.06.2020 13:07, Eli Zaretskii wrote:
> > > In any case, my proposal was not about the API itself, it was more
> > > about the implementation of the API.  For example, we could have an
> > > implementation of the generic project-files API that consulted some
> > > list instead of asking the VCS or the filesystem to provide the files.
> >
> > You can of course do this already, in 10 lines or so.
>
> I'm a user.  I don't want to write code every time I want something
> simple from the project-related commands.  I expect such simple use
> cases to be supported OOTB.

I think we're generally comfortable recommending users customize 
something in their init script, if that's a one-off request, and nobody 
else comes with the same request.

Of course, when such customization turns out to be useful and elegant 
enough, we can always incorporate it later.

For less technical users, we sometimes offer a snippet to use.

Even if you just do this for yourself, it can be a valuable of the API 
is defined, whether it can support your usage scenario this way.

> > But imagine you did add such a backend where project-files returns an
> > arbitrary list of files. And you use it.
> >
> > How would project-switch-to-buffer consult it? Will it have to call
> > project-files now, as opposed to just using project-root as the basis
> > for comparison? And then compare buffer-file-name of all file-visiting
> > buffers against that list?
>
> That's one possibility, yes.

I'm asking for a concrete suggestion, if you have it.

And I have just outlined a problem with the most obvious approach.

> > That would work for smaller projects, but in large ones project-files is
> > not instantaneous, so they will be penalized in performance by such an
> > approach.
>
> We have faster data structures than lists.  We could use them.

List as a data structure is a secondary problem. Big projects can take a 
while to fetch that list.

> And in any case, we should identify the needs first, and then
> implement the features that support those needs.  Rejecting some of
> the needs because they don't fit the current implementation is the
> wrong way for designing features such as this, which is supposed to be
> part of our IDE infrastructure.

As outlined above, even if I recommend trying to implement a usage 
pattern in one's init script first, that doesn't necessarily mean I 
rejected it.

> > And project-switch-to-buffer should work with all kinds of projects.
>
> Yes.  And one such kind is an ad-hoc collection of files and buffers,
> where only the user knows which ones he/she is interested in and which
> ones he/she isn't.  Every IDE I saw supports something like that, so
> we should do that as well, IMO.

I'm curious about those "every IDE". I don't recall such a feature in 
ones I tried. Perhaps I just didn't use it, of course.

> > That also wouldn't solve the problem of non-file-visiting buffers like
> > Grep from your example.
>
> You talked about project-files, so buffers that don't visit files are
> excluded, of course.  But an indication that supports marking buffers
> as belonging to a project could support both file-visiting and non
> file-visiting buffers.

Buffers are essentially transient. An indication could be a list of 
files, but the project API has no provision for "list of buffers", and 
such a thing has never come up until now.

So my first instinct would be to make this customizable through some 
hook, rather than extend the API.