Re: master 0339325: ; * lisp/progmodes/project.el (project-current): Doc fix.

[Eli Zaretskii]

> Cc: emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Mon, 13 Jul 2020 14:09:54 +0300
> 
> >>     except for those that are ignored
> >>     in the default 'project-ignores' implementation.
> >>
> >> But this is basically a tautology. If we wanted to describe transient's
> >> particular behavior we'd have to describe what it actually ignores (and
> >> it honors vc-directory-exclusion-list as well as
> >> grep-find-ignored-files). But that pretty clunky for one docstring.
> > 
> > Which is why I just mentioned the function which implements all that.
> 
> Thing is, it's a generic function. It has multiple implementations, so 
> saying 'per project-ignores' is not very informative.

What I wrote talks only about the "transient" project, which AFAIU
uses the default implementation.  So I think it's as informative as
possible in this case.

But if you can come up with a better wording which doesn't lose useful
information, please do.

Btw, your implementation style makes it unusually hard to write good
doc strings.  I'm not quite sure why, but one possible reason is that
IMO you bring the generics too high, too close to the application
level, where doc strings should be more and more user-oriented.  When
this is coupled with your reluctance, to say the least, to disclose
details of what you consider to be opaque objects, it becomes hard to
say anything useful about many functions, because describing what
functions do usually involves talking about their inputs and outputs,
and how the former are processed into the latter.  The "for example"
method that I tried to use was about the only technique I could think
of to overcome those difficulties, and you reject even that.

Whether one agrees with your coding style or not, the difficulties it
presents to documenting our code are real, and I suggest that you
consider this disadvantage seriously, because it basically flies in
the face of long-standing traditions of Emacs self-documenting
features.

> > You cannot usefully refer to the default implementation without saying
> > that this or that types of project use the default implementation,
> > which is IMO against your information encapsulation policies.
> 
> I think I see the reason for your choice. But I'm saying we can describe 
> the behavior of project-ignores for that value.

Feel free to propose such a description, if you think such details are
important for a transient object.

> Like we already described the behavior of 'project-root' for that value 
> earlier in the same sentence ("denotes a project rooted in that directory").

That is actually quite vague.  It gives you some idea what such a
project means, but if you take it apart, it is just a fancy way of
saying that this project knows where its root is, and nothing else.

> While in general we might not want the consumers of project-current 
> depend on particular behavior of either of these generic functions when 
> using backends retrieved in the "normal" way, this is a special, 
> fallback case that can inform the user of the behavior of said fallback 
> backend. If we had a better place to describe that behavior in, though, 
> we could move that there.

The description of the transient project doesn't have to be detailed,
because it's, well, transient.  Its documentation needs to give some
idea what it is and how it is used; anything else is not a necessity,
IMO.