project.el semantics

[Stephen Leake]

Dmitry Gutov <address@hidden> writes:

> On 09/17/2015 12:01 AM, Stephen Leake wrote:
>
>> Does this mean file name completion should search on project-roots, not
>> project-search-path, for this use case?
>
> Err, that looks like a non-sequitur to me. project-find-file should
> search in where it's defined to search (up to you). It just occurs to
> me that some users might expect it to only list files in the currently
> opened project(s), whereas other users would like to jump to system
> include files as well.
>
>> xref-find-regexp searches on both, which is redundant. For example, for
>> a file in Emacs core, using only project-try-vc in project-find-files,
>> project-roots returns ("c:/Projects/emacs/master/"), and
>> project-search-path includes that directory along with others.
>
> It's kinda redundant, but as long we define project-search-path as a
> list of directories with *source* files, it may omit the root
> directories if they contain only, say, documentation. But we want
> xref-find-regexp to search in documentation as well.

Both find-file-in-project and xref-find-regexp are client code using the
project API.

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

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.

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.

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

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.

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

-- 
-- Stephe