bug#56809: file-name-with-extension: Improve docstring.

[Eli Zaretskii <eliz@gnu.org>]

> From: Damien Cassou <damien@cassou.me>
> Cc: 56809@debbugs.gnu.org
> Date: Thu, 28 Jul 2022 11:32:55 +0200
> 
> >>> "Return FILENAME modified to…
> >> 
> >> Most readers will know that FILENAME is not going to be modified but the
> >> phrasing is still confusing in my opinion.
> >
> > Why confusing?
> 
> To me, "Return FILENAME modified" means that FILENAME is going to be
> modified but that is not true: FILENAME will still reference the same
> place in memory and this place won't be changed either. Said
> differently: I understand the sentence as "there is going to be some
> side-effects" even though there are none.

Well, the "return" part was supposed to prevent such an
interpretation.  Moreover, that sentence is just the summary; the doc
string goes on to say

  This function removes any existing extension from FILENAME, and then
  appends EXTENSION to it.

I could have the first sentence to say something like

  Return a file name made from the base name of FILENAME and EXTENSION.

But is this really better?  We'd need at least to explain what is a
"base name" (and it's also a bit inaccurate, since "base name"
generally means without the leading directories).

> I agree it is inaccurate. The inaccuracy is acceptable to me in the
> first sentence as this sentence is only meant to give an idea of what
> the function is supposed to do. The rest of the docstring explains the
> details and why it's not a simple concatenation.

Well, the same is true for the "modified" part, isn't it?

> As a conclusion, I'm fine with the docstring and you should merge it and
> do more important stuff rather than discussing unimportant details with
> me 😃. I'm sorry I made you loose your time.

No need to be sorry, this is part of my job as a maintainer.

Thanks.