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

[Dmitry Gutov <dgutov@yandex.ru>]

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.