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

[Dmitry Gutov]

On 11.07.2020 09:58, Eli Zaretskii wrote:

> > Tramp has extra-special handling for VC. It probably wouldn't be able to
> > do that for all possible project backends.
>
> Why assume the worse?  The situation is no different from that with
> VC, so I see no reason to assume Tramp will do something similar for
> supporting project.el.

We shall see.

> > - The "current project" cache of said buffer (if it is already visited)
> > needs to be invalidated.
> > - The "project-files" cache (currently not cached) of said project needs
> > to be invalidated as well.
> >
> > When a file is removed from project, the latter needs to happen.
>
> Having commands to add or remove files from the project would allow us
> to advertise those commands as the supported means of doing so.  We
> could also have a command to "refresh" the project, for those who for
> some reasons will prefer doing that externally.

These are options, of course. But this will make Emacs project support 
more high-maintenance than in "other editors".

Take a random modern editor, open an existing project in it (it will 
show up in the side panel, usually). Then create a new file in its root 
directory using some external means. If it's not ignored by existing 
configuration, it will automatically show in the project drawer as well.

We should support that.

> But even without such
> a command, we could say that users will have to go the project.el way
> to have their project always up to date with the files it consists of,
> and discourage doing that by external means.

What's the project.el way? I suppose we could add hooks to find-file, 
dired-delete-file and after-save-hook in .dir-locals.el, if we give up 
on this kind of feature parity.

> > The exact logic of project-current depends on the configuration of
> > project-find-functions.
>
> Exactly.  Then mentioning that as well would also help.

Sounds good.

> > > > >      . the new doc string is confusing: "if 'project-current' returns the
> > > > >        same (equal) value" is incomplete, because it doesn't say the same
> > > > >        as what
> > > >
> > > > Same as the current project value, if any (otherwise, same as the value
> > > > returned by the project selection prompt).
> > >
> > > Please fix the sentence, then.
> >
> > I'll do my best.
>
> I see you simply reverted to the original wording, more or less, which
> is what prompted me to improve it.  If you are still working on
> improving that, I will wait;

I "fixed" it to match the docstring of another command which you also 
improved in the past. Guessing that it could be good enough.

> but if this is what you think the doc
> string should say, then I will fix it again to be better.

That sounds threatening.

Like I said, you're welcome to suggest a better phrasing, for this and 
the other command (as long as the descriptions remain accurate). Go 
ahead and commit the new versions, if you like.