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

From: Eli Zaretskii <[email-masked]>
Date: Thu, 28 Jul 2022 11:57:25 +0300

> From: Damien Cassou <[email-masked]>
> Cc: [email-masked]
> Date: Thu, 28 Jul 2022 10:35:01 +0200
> 
> Eli Zaretskii <[email-masked]> writes:
> > Looks OK?
> 
> looks better than my version :-). The only thing I don't really like is
> 
> > "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?  And what do you mean by "will know that FILENAME is
not going to be modified"?

> I would prefer a version
> around the word "concatenate" or similar. Here is another version:
> 
>   Concatenate FILENAME without its extension and EXTENSION.

I don't want to say how the function does its job: that's not what a
doc string should describe.  ("Concatenate" is also inaccurate,
because if EXTENSION lacks the leading period, that's not really
what's going on there.)  So please help me understand why "modified"
is problematic, and let's take it from there.

Thanks.