Re: project.el semantics

[Dmitry Gutov]

On 09/18/2015 07:08 PM, Stephen Leake wrote:

> In order to use the API correctly, the semantics of each call must be
> well-defined.

No argument here.

> That means it must be possible to tell from the API as defined by
> project.el (and some future project.texi) what functions to call for
> these two uses. They cannot rely on vague guesses about what some
> backend might do, or what the user might want.

Yes, we need more documentation. Please simply consider the grand-parent 
email as bringing up an example of another use-case we might want to 
support.

> That means project-search-path should be clearly defined to be either
> purely recursive or not, so client code and project backends know
> whether to weed out duplicates or not.

Let's call it "redundant", or "non-redundant". The issue seems different 
from the "flat" search-path we've discussed previously.

> It also means the distinction between project-search-path and
> project-roots must be more clearly defined.

Sure. We need more clarity WRT to redundancy in the search path, maybe 
better docstrings (although it's not immediately clear to me how to 
improve the current wording), and some good examples in the manual.

> If there are use cases where different search paths are desired for
> different purposes (such as "source" vs "documentation" above), the
> the project API must provide a clear mechanism to distinguish those
> cases, so the appropriate search path can be returned.

But what are those different purposes? So far, the distinction as I 
understand it is that search-path contains actual source files, and 
project-roots can contain anything else. So it's just source files vs 
any files.

> The current doc strings for project-search-path and project-roots do not
> make that clear, and the way they are used and implemented in current
> code makes project-roots purely redundant (no code would be harmed by
> simply deleting it, and some would be improved thru reduced redundancy).

The default implementations don't have enough information to do better. 
Would you delete the default project-search-path implementation? Then 
what will the VC-backend implementation of it look like?