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

Previous Next

Full log

Message #14 received at 56809 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Damien Cassou <damien <at> cassou.me>
Cc: 56809 <at> debbugs.gnu.org
Subject: Re: bug#56809: file-name-with-extension: Improve docstring.
Date: Thu, 28 Jul 2022 11:57:25 +0300

> From: Damien Cassou <damien <at> cassou.me>
> Cc: 56809 <at> debbugs.gnu.org
> Date: Thu, 28 Jul 2022 10:35:01 +0200
> 
> Eli Zaretskii <eliz <at> gnu.org> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.