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?