Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for project-remember/forget-under

From: Dmitry Gutov <[email-masked]>
Date: Mon, 17 Feb 2025 05:27:56 +0200

On 14/02/2025 10:30, Eli Zaretskii wrote:
>> Date: Fri, 14 Feb 2025 05:58:38 +0200
>> Cc: [email-masked], [email-masked]
>> From: Dmitry Gutov <[email-masked]>
>>
>> On 13/02/2025 09:28, Eli Zaretskii wrote:
>>
>>> IMO, this:
>>>
>>>     +Display a message at the end summarizing what was found.
>>>     +Return the number of detected projects."
>>>
>>> contrasts strangely with this:
>>>
>>>     +Display a message at the end summarizing what was forgotten.
>>>     +Return the number of forgotten projects."
>>>
>>> If we say "forgotten" in the latter case, why do we say "found" (and
>>> not, for example, "remembered" or "new" or "added") in the former?
>>> Doesn't the latter case also "find" projects?
>>
>> It wouldn't include the project that were found in the second scan but
>> weren't "known" previously.
> 
> So you mean the number of previously-known projects that will no
> longer be known?

Yep.

> In that case, should the doc string for project-remember say something
> like "the number of newly-remembered projects"?

Sure.

>>> Also, this:
>>>
>>>     Remember projects below a directory DIR.
>>>
>>> is in contrast with this:
>>>
>>>     Forget all known projects below a directory DIR.
>>>
>>> Why doesn't the former say "all the projects", but the latter does?
>>
>> Good question, I think the latter should not have "all" as well. I think
>> "all" implies the recursive search, at least in some readings.
> 
> And maybe "below" should be "in", so as not to hint on recursive
> descent?

In my reading these mean the same (as opposed to "directly below"), but 
if it helps from your POV - very good.

>>> And a final nit: should we somehow explain in the doc string what it
>>> means to "remember" and to "forget" in this context?
>>
>> Not sure, but we could say that it means adding to and removing from the
>> "known projects list".
> 
> I think adding the reference to the list would be good.

Hmm, I'm not sure what would be a good approach which would not restate 
something already obvious from the text a second time. We could abolish 
both verbs from the docstring ("remember" and "forget"), saying instead 
"add to known projects" and "remove from known projects" - but the 
result would be longer on multiple lines. Longer text can be inherently 
less clear.