[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Dmitry Gutov
Subject: Re: master 0339325: ; * lisp/progmodes/project.el (project-current): Doc fix.
Date: Mon, 13 Jul 2020 14:09:54 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0

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.

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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]