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

[Eli Zaretskii]

> Cc: theo@thornhill.no, philip@warpmail.net, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Fri, 10 Jul 2020 22:36:48 +0300
> 
> >> Which is most likely a plus for Tramp, we don't need to make buffer
> >> opening even slower there.
> > 
> > We could have a defcustom to disable that for those who will seldom
> > if ever use project.el.  And again, we do that for VC.
> 
> 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.

> >> Removal also happens through different venues (removal in Dired, on 'rm'
> >> in the terminal, or changing the project configuration to ignore the
> >> said file).
> > 
> > Why should we care about adding or removing a file that are not
> > visited in Emacs?
> 
> A file already opened in Emacs might be added to some project this way 
> (by editing project config, or doing 'git init'). Then, ideally, two 
> things need to happen:
> 
> - 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.  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.

> >>>     . it makes the doc string of project-switch-to-buffer intentionally
> >>>       obfuscated by "explaining" stuff in terms of the implementation,
> >>>       which makes it not very useful (as I already tried to explain in
> >>>       the past)
> >>
> >> What are you suggesting?
> > 
> > Explain what project-current does, most probably, right in that doc
> > string.
> 
> project-current finds the current project of the buffer. Or the project 
> to which the current buffer is related. Would that explanation make 
> things better?

No, because that's not enough detail.

> The exact logic of project-current depends on the configuration of 
> project-find-functions.

Exactly.  Then mentioning that as well would also help.

> >>>     . 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; but if this is what you think the doc
string should say, then I will fix it again to be better.

> >>> So that commit looks like a step backwards to me.
> >>
> >> Just because you don't like the new docstring?
> >>
> >> That's harsh.
> > 
> > I didn't see any other significant changes, sorry.
> 
> You asked for the buffer-matching logic not to depend on 
> default-directory anymore. It doesn't.
> 
> Now project-switch-to-buffer and project-kill-buffers should work with 
> Stephen's backend, as well as any "manually managed project" backend you 
> might choose to write.

Yes, and that's good.  Thanks.