Spencer Baugh writes: > Eli Zaretskii writes: >>> From: Spencer Baugh >>> 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. > > OK, how about this? Oops, that one didn't include the updated project-uniquify-dirname-transform docstring. The right patch now: