bug#62621: 29.0.60; uniquify can't make buffers unique based on things other than filename

[Eli Zaretskii <eliz@gnu.org>]

> From: Spencer Baugh <sbaugh@janestreet.com>
> Cc: dmitry@gutov.dev,  62621@debbugs.gnu.org,  sbaugh@catern.com
> Date: Fri, 21 Jul 2023 09:34:28 -0400
> 
> > Thanks, but it still falls short of what Dmitry described above: the
> > doc string doesn't "mention several functions that can be used".
> >
> >> +(defcustom uniquify-dirname-transform #'identity
> >> +  "Function to transform buffer's directory for uniquifying its name.
> >> +
> >> +It takes a single argument: the directory of the buffer.  It
> >> +should return a string filename (which does not need to actually
> >> +exist in the filesystem) to use for uniquifying the buffer name."
> >
> > Please read this carefully and try to put yourself in the shoes of a
> > user who needs to make sense out of this description.  The immediate
> > question I had is what does "transforming a buffer's directory" have
> > to do with "uniquifying the buffer name"?  Uniquifying a buffer's name
> > is not about its directory, at least not in general.  IOW, the
> > starting point of this description is too "inside" the implementation.
> 
> OK, how about this?

The explanation of what project-uniquify-dirname-transform does should
in its doc string, not in the doc string of uniquify-dirname-transform
(which should refer to the former, and that is enough).

The doc string of uniquify-dirname-transform should mention at least
'identity' as the default (what you wrote does that, but without
mentioning the function's name), otherwise this still falls short of
what Dmitry described.

And the last two paragraphs of the doc string of
uniquify-dirname-transform should be more-or-less reversed: first
describe the default, and that using some function other than
'identity' can affect the result, then describe
project-uniquify-dirname-transform as one such non-default transform.