[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#56809: file-name-with-extension: Improve docstring.
From: |
Eli Zaretskii |
Subject: |
bug#56809: file-name-with-extension: Improve docstring. |
Date: |
Thu, 28 Jul 2022 12:40:37 +0300 |
> 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.