master d8e17a4 1/2: Another minor improvement of project.el doc strings

[Eli Zaretskii]

branch: master
commit d8e17a4c4e0c2770fabf48b62a1a071671534431
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Another minor improvement of project.el doc strings
    
    * lisp/progmodes/project.el (project-find-functions)
    (project-current, project-switch-to-buffer): Doc fix.
    (project-current): Rename the argument DIR to DIRECTORY.
---
 lisp/progmodes/project.el | 39 ++++++++++++++++++++++++++-------------
 1 file changed, 26 insertions(+), 13 deletions(-)

diff --git a/lisp/progmodes/project.el b/lisp/progmodes/project.el
index ce80465..af02af7 100644
--- a/lisp/progmodes/project.el
+++ b/lisp/progmodes/project.el
@@ -101,30 +101,37 @@
 (defvar project-find-functions (list #'project-try-vc)
   "Special hook to find the project containing a given directory.
 Each functions on this hook is called in turn with one
-argument (the directory) and should return either nil to mean
-that it is not applicable, or a project instance.")
+argument, the directory in which to look, and should return
+either nil to mean that it is not applicable, or a project instance.
+The exact form of the project instance depends on the respective
+function; for example, the default `project-try-vc' returns a
+cons cell of the form (vc . PROJECT-ROOT-DIRECTORY).")
 
 (defvar project-current-inhibit-prompt nil
   "Non-nil to skip prompting the user in `project-current'.")
 
 ;;;###autoload
-(defun project-current (&optional maybe-prompt dir)
-  "Return the project instance in DIR or `default-directory'.
-When no project found in DIR, and MAYBE-PROMPT is non-nil, ask
-the user for a different project to look in."
-  (unless dir (setq dir default-directory))
-  (let ((pr (project--find-in-directory dir)))
+(defun project-current (&optional maybe-prompt directory)
+  "Return the project instance in DIRECTORY, defaulting to `default-directory'.
+When no project is found in that directory, and MAYBE-PROMPT
+is non-nil, ask the user for a directory in which to look for the project.
+If no project is found, return nil.
+
+See the doc string of `project-find-functions' for the form of the
+project instance object."
+  (unless directory (setq directory default-directory))
+  (let ((pr (project--find-in-directory directory)))
     (cond
      (pr)
      ((unless project-current-inhibit-prompt
         maybe-prompt)
-      (setq dir (project-prompt-project-dir)
-            pr (project--find-in-directory dir))))
+      (setq directory (project-prompt-project-dir)
+            pr (project--find-in-directory directory))))
     (when maybe-prompt
       (if pr
           (project--add-to-project-list-front pr)
-        (project--remove-from-project-list dir)
-        (setq pr (cons 'transient dir))))
+        (project--remove-from-project-list directory)
+        (setq pr (cons 'transient directory))))
     pr))
 
 (defun project--find-in-directory (dir)
@@ -802,7 +809,13 @@ Arguments the same as in `compile'."
 
 ;;;###autoload
 (defun project-switch-to-buffer ()
-  "Switch to another buffer belonging to the current project."
+  "Switch to another buffer belonging to the current project.
+This function prompts for another buffer, offering as candidates
+buffers that belong to the same project as the current buffer.
+Two buffers belong to the same project if their project instances,
+as reported by `project-current' in each buffer, are identical.  See
+the doc string of `project-find-functions' for the forms a project
+instance object can take."
   (interactive)
   (let* ((pr (project-current t))
          (current-buffer (current-buffer))