bug#64266: [PATCH] ; * lisp/progmodes/project.el (project-current): Doc fix.

bug#64266: [PATCH] ; * lisp/progmodes/project.el (project-current): Doc fix.

[Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 1034 bytes --]

Tags: patch

Hi,

Since commit 9efa6d2cf28f4e21f23bb0dbfedc59a4286dab12, the function
`project-current` uses the function specified by `project-prompter`
rather than calling `project-prompt-project-dir` directly.  As a result,
it can prompt for a project by its name rather than by its root
directory (depending on the value of `project-prompter`), but the doc
string of `project-current` says that it "asks the user for a directory"
without mentioning `project-prompter`.  This patch clarifies that
`project-current` uses `project-prompter` for prompting.


In GNU Emacs 30.0.50 (build 18, x86_64-apple-darwin22.5.0, NS
 appkit-2299.60 Version 13.4 (Build 22F66)) of 2023-06-24 built on
 Dazzs-MBP
Repository revision: 77c2f05d773271cb59ebfd994b06a4075cacbfa8
Repository branch: master
Windowing system distributor 'Apple', version 10.3.2299
System Description:  macOS 13.4

Configured using:
 'configure 'CFLAGS=-g0 -O3' --with-native-compilation --with-json
 --with-imagemagick --with-tree-sitter --enable-link-time-optimization'


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-progmodes-project.el-project-current-Doc-fix.patch --]
[-- Type: text/patch, Size: 1388 bytes --]

From 8dbf48e71fd68b10478a70ec8453e5e0c61e176d Mon Sep 17 00:00:00 2001
From: Eshel Yaron <me@eshelyaron.com>
Date: Sat, 24 Jun 2023 17:16:19 +0300
Subject: [PATCH] ; * lisp/progmodes/project.el (project-current): Doc fix.

Avoid saying that 'project-current' asks specifically for a directory,
as it can also ask for a project's directory by other identifiers,
such as the project's name, when 'project-prompter' is set to a
different value than the default 'project-prompt-project-dir'.
---
 lisp/progmodes/project.el | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/lisp/progmodes/project.el b/lisp/progmodes/project.el
index 56c524bcab5..5e8628bbd0e 100644
--- a/lisp/progmodes/project.el
+++ b/lisp/progmodes/project.el
@@ -219,9 +219,9 @@ project-current
 
 When no project is found in that directory, the result depends on
 the value of MAYBE-PROMPT: if it is nil or omitted, return nil,
-else ask the user for a directory in which to look for the
-project, and if no project is found there, return a \"transient\"
-project instance.
+else call the function specified by `project-prompter' to prompt
+the user for a project's directory, and if no project is found
+there, return a \"transient\" project instance.
 
 The \"transient\" project instance is a special kind of value
 which denotes a project rooted in that directory and includes all
-- 
2.41.0

bug#64266: [PATCH] ; * lisp/progmodes/project.el (project-current): Doc fix.

[Eli Zaretskii]

> Date: Sat, 24 Jun 2023 17:35:12 +0300
> From:  Eshel Yaron via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> diff --git a/lisp/progmodes/project.el b/lisp/progmodes/project.el
> index 56c524bcab5..5e8628bbd0e 100644
> --- a/lisp/progmodes/project.el
> +++ b/lisp/progmodes/project.el
> @@ -219,9 +219,9 @@ project-current
>  
>  When no project is found in that directory, the result depends on
>  the value of MAYBE-PROMPT: if it is nil or omitted, return nil,
> -else ask the user for a directory in which to look for the
> -project, and if no project is found there, return a \"transient\"
> -project instance.
> +else call the function specified by `project-prompter' to prompt
> +the user for a project's directory, and if no project is found
> +there, return a \"transient\" project instance.

This starts by describing the implementation instead of describing the
behavior first.  The doc string will be more useful if reworded like
this:

 When no project is found in that directory, the result depends on
 the value of MAYBE-PROMPT: if it is nil or omitted, return nil,
 else prompt the user for the project to use.
 To prompt for a project, call the function specified  by
 `project-prompter', which returns the directory in which to
 look for the project.  If no project is found in that directory,
 return a \"transient\" project instance.  

OK?

bug#64266: [PATCH] ; * lisp/progmodes/project.el (project-current): Doc fix.

[Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>>  When no project is found in that directory, the result depends on
>>  the value of MAYBE-PROMPT: if it is nil or omitted, return nil,
>> -else ask the user for a directory in which to look for the
>> -project, and if no project is found there, return a \"transient\"
>> -project instance.
>> +else call the function specified by `project-prompter' to prompt
>> +the user for a project's directory, and if no project is found
>> +there, return a \"transient\" project instance.
>
> This starts by describing the implementation instead of describing the
> behavior first.  The doc string will be more useful if reworded like
> this:
>
>  When no project is found in that directory, the result depends on
>  the value of MAYBE-PROMPT: if it is nil or omitted, return nil,
>  else prompt the user for the project to use.
>  To prompt for a project, call the function specified  by
>  `project-prompter', which returns the directory in which to
>  look for the project.  If no project is found in that directory,
>  return a \"transient\" project instance.  
>
> OK?

Yes, that's clearer, thanks.  Should I send an updated patch?

bug#64266: [PATCH] ; * lisp/progmodes/project.el (project-current): Doc fix.

[Eli Zaretskii]

> From: Eshel Yaron <me@eshelyaron.com>
> Cc: 64266@debbugs.gnu.org
> Date: Sat, 24 Jun 2023 18:32:00 +0300
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >  When no project is found in that directory, the result depends on
> >  the value of MAYBE-PROMPT: if it is nil or omitted, return nil,
> >  else prompt the user for the project to use.
> >  To prompt for a project, call the function specified  by
> >  `project-prompter', which returns the directory in which to
> >  look for the project.  If no project is found in that directory,
> >  return a \"transient\" project instance.  
> >
> > OK?
> 
> Yes, that's clearer, thanks.  Should I send an updated patch?

I would recommend waiting for Dmitry and Spencer to chime in, and
submit a followup after their comments, if any.

bug#64266: [PATCH] ; * lisp/progmodes/project.el (project-current): Doc fix.

[Dmitry Gutov]

On 24/06/2023 20:06, Eli Zaretskii wrote:
> I would recommend waiting for Dmitry and Spencer to chime in, and
> submit a followup after their comments, if any.

Your suggested versions sounds good to me too, thanks.

bug#64266: [PATCH] ; * lisp/progmodes/project.el (project-current): Doc fix.

[Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 388 bytes --]

Dmitry Gutov <dmitry@gutov.dev> writes:

> On 24/06/2023 20:06, Eli Zaretskii wrote:
>> I would recommend waiting for Dmitry and Spencer to chime in, and
>> submit a followup after their comments, if any.
>
> Your suggested versions sounds good to me too, thanks.

Thanks, I'm attaching an updated patch following Eli's wording.

Also CC'ing Spencer in case there are further comments.



[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v2-0001-lisp-progmodes-project.el-project-current-Doc-fix.patch --]
[-- Type: text/x-patch, Size: 1400 bytes --]

From 8b41814b8dc52b50098a8282d9fb63cdec695a4e Mon Sep 17 00:00:00 2001
From: Eshel Yaron <me@eshelyaron.com>
Date: Sat, 24 Jun 2023 17:16:19 +0300
Subject: [PATCH v2] ; * lisp/progmodes/project.el (project-current): Doc fix.

Avoid saying that 'project-current' asks specifically for a directory,
as it can also ask for a project's directory by other identifiers,
such as the project's name, when 'project-prompter' is set to a
different value than the default 'project-prompt-project-dir'.
---
 lisp/progmodes/project.el | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/lisp/progmodes/project.el b/lisp/progmodes/project.el
index 56c524bcab5..0f47c217d80 100644
--- a/lisp/progmodes/project.el
+++ b/lisp/progmodes/project.el
@@ -219,8 +219,10 @@ project-current
 
 When no project is found in that directory, the result depends on
 the value of MAYBE-PROMPT: if it is nil or omitted, return nil,
-else ask the user for a directory in which to look for the
-project, and if no project is found there, return a \"transient\"
+else prompt the user for the project to use.  To prompt for a
+project, call the function specified by `project-prompter', which
+returns the directory in which to look for the project.  If no
+project is found in that directory, return a \"transient\"
 project instance.
 
 The \"transient\" project instance is a special kind of value
-- 
2.41.0

bug#64266: [PATCH] ; * lisp/progmodes/project.el (project-current): Doc fix.

[sbaugh]

Eshel Yaron <me@eshelyaron.com> writes:
> Dmitry Gutov <dmitry@gutov.dev> writes:
>
>> On 24/06/2023 20:06, Eli Zaretskii wrote:
>>> I would recommend waiting for Dmitry and Spencer to chime in, and
>>> submit a followup after their comments, if any.
>>
>> Your suggested versions sounds good to me too, thanks.
>
> Thanks, I'm attaching an updated patch following Eli's wording.
>
> Also CC'ing Spencer in case there are further comments.

LGTM

bug#64266: [PATCH] ; * lisp/progmodes/project.el (project-current): Doc fix.

[Eli Zaretskii]

> From: Eshel Yaron <me@eshelyaron.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,  64266@debbugs.gnu.org, sbaugh@catern.com
> Date: Sun, 09 Jul 2023 10:57:13 +0300
> 
> Dmitry Gutov <dmitry@gutov.dev> writes:
> 
> > On 24/06/2023 20:06, Eli Zaretskii wrote:
> >> I would recommend waiting for Dmitry and Spencer to chime in, and
> >> submit a followup after their comments, if any.
> >
> > Your suggested versions sounds good to me too, thanks.
> 
> Thanks, I'm attaching an updated patch following Eli's wording.
> 
> Also CC'ing Spencer in case there are further comments.

Thanks, installed on the master branch, and closing the bug.