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

[Dmitry Gutov]

On 13.07.2020 06:48, Eli Zaretskii wrote:
> > From: Dmitry Gutov <dgutov@yandex.ru>
> > Date: Sun, 12 Jul 2020 23:07:46 +0300
> >
> > On 12.07.2020 21:49, Eli Zaretskii wrote:
> > >    The \"transient\" project instance is a special kind of value
> > >    which denotes a project rooted in that directory and includes all
> > > -files under it except for ones that match standard ignores.
> > > +the files under the directory except for those that should be
> > > +ignored (per `project-ignores').
> >
> > The more accurate way to say this
>
> What isn't accurate in what I wrote?  (The point being that 'standard
> ignores" is something never mentioned in any other function or
> variable in project.el, and so this term is unknown and confusing.)

You were right to change it, but I'm talking about a further improvement.

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

> > So
> > perhaps that description should move somewhere. Into the Commentary,
> > maybe. Or directly to the cl-defgeneric's docstring, to which
> > project-current's docstring would after all refer to as "the default
> > `project-ignores' implementation".
>
> 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.

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

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.