From: Eli Zaretskii <eliz@gnu.org>
Date: Wed, 26 Jul 2023 15:11:49 +0000 (+0300)
Subject: ; Documentation followup to last change
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=6572dcc7f5db90a32c35ef43788a8b29a07a0c2c;p=emacs.git

; Documentation followup to last change

* lisp/progmodes/project.el (project-uniquify-dirname-transform):
* lisp/uniquify.el (uniquify-dirname-transform): Doc fixes.

* etc/NEWS: Announce the change.
---

diff --git a/etc/NEWS b/etc/NEWS
index e81bc223836..d0dab755212 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -102,6 +102,15 @@ plus, minus, check-mark, start, etc.
 The 'tool-bar-position' frame parameter can be set to 'bottom' on all
 window systems other than Nextstep.
 
+---
+** New user option 'uniquify-dirname-transform'.
+This can be used to customize how buffer names are uniquified, by
+making arbitrary transforms on the buffer's directory name (whose
+components are used to uniquify buffer names when they clash).  You
+can use this to distinguish between buffers visiting files with the
+same base name that belong to different projects by using the provided
+transform function 'project-uniquify-dirname-transform'.
+
 ** cl-print
 
 *** You can expand the "..." truncation everywhere.
diff --git a/lisp/progmodes/project.el b/lisp/progmodes/project.el
index e7deee43f8e..eac6a60f5bf 100644
--- a/lisp/progmodes/project.el
+++ b/lisp/progmodes/project.el
@@ -1889,12 +1889,12 @@ to directory DIR."
 
 ;;;###autoload
 (defun project-uniquify-dirname-transform (dirname)
-  "Include `project-name' in DIRNAME if in a project.
+  "Uniquify name of directory DIRNAME using `project-name', if in a project.
 
 If you set `uniquify-dirname-transform' to this function,
-slash-separated components from `project-name' will be added to
-the buffer's name when buffers from two different projects would
-otherwise have the same name."
+slash-separated components from `project-name' will be appended to
+the buffer's directory name when buffers from two different projects
+would otherwise have the same name."
   (if-let (proj (project-current nil dirname))
       (let ((root (project-root proj)))
         (expand-file-name
diff --git a/lisp/uniquify.el b/lisp/uniquify.el
index af00c95663d..2ad2fb0eeac 100644
--- a/lisp/uniquify.el
+++ b/lisp/uniquify.el
@@ -169,25 +169,26 @@ That means that when `buffer-file-name' is set to nil, `list-buffers-directory'
 contains the name of the directory which the buffer is visiting.")
 
 (defcustom uniquify-dirname-transform #'identity
-  "Function to transform buffer's directory for uniquifying its name.
-
-If `uniquify-buffer-name-style' is non-nil and a buffer's name
-would be the same as some other buffer, then components from the
-buffer's directory name are added to the buffer's name until the
-buffer's name is unique.
-
-This function is used to transform the buffer's directory name
-before the uniquifying process, allowing the unique buffer name
-to include components from other sources.  The default is
-`identity', so only the buffer's directory name is used for
-uniquifying.  This function is called with the buffer's directory
-name and should return a file name (which does not need to
-actually exist in the filesystem) to use components from.
-
-To include components from `project-name', set this variable to
-`project-uniquify-dirname-transform'."
-  :type '(choice (function-item :tag "Don't change the dirname" identity)
-                 (function-item :tag "Include project name in dirname"
+  "Function to transform buffer's directory name when uniquifying buffer's name.
+
+When `uniquify-buffer-name-style' is non-nil, Emacs makes buffer
+names unique by adding components of the buffer's directory name
+until the resulting name is unique.  This function is used to
+transform the buffer's directory name during this uniquifying
+process, allowing the unique buffer name to include strings
+from sources other than the buffer's directory.  The default is
+`identity', so the unmodified buffer's directory name is used for
+uniquifying.
+
+This function is called with the buffer's directory name and
+should return a string which names a file (that does not need to
+actually exist in the filesystem); the components of this file
+name will then be used to uniquify the buffer's name.
+
+To include components from the `project-name' of the buffer, set
+this variable to `project-uniquify-dirname-transform'."
+  :type '(choice (function-item :tag "Use directory name as-is" identity)
+                 (function-item :tag "Include project name in directory name"
                                 #'project-uniquify-dirname-transform)
                  function)
   :version "30.1"