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

Previous Next

Full log

Message #20 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 12:40:37 +0300

> From: Damien Cassou <damien <at> cassou.me>
> Cc: 56809 <at> 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.

Previous Next

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