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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 56809 in the body.
You can then email your comments to 56809 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Damien Cassou <damien <at> cassou.me>
To: bug-gnu-emacs <at> gnu.org
Subject: file-name-with-extension: Improve docstring.
Date: Thu, 28 Jul 2022 08:31:24 +0200

[Message part 1 (text/plain, inline)]

Tags: patch

Hi,

I found the docstring of file-name-with-extension very confusing so I
wrote another one.

Best

-- 
Damien Cassou

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

[0001-lisp-files.el-file-name-with-extension-Improve-docst.patch (text/patch, attachment)]

Message #8 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 10:49:16 +0300

> From: Damien Cassou <damien <at> cassou.me>
> Date: Thu, 28 Jul 2022 08:31:24 +0200
> 
> I found the docstring of file-name-with-extension very confusing so I
> wrote another one.

Thanks.  It definitely needed its wording and its grammar fixed.

I've now fixed that on the emacs-28 release branch.  The modified doc
string says this:

    "Return FILENAME modified to have the specified EXTENSION.
  The extension (in a file name) is the part that begins with the last \".\".
  This function removes any existing extension from FILENAME, and then
  appends EXTENSION to it.

  EXTENSION may include the leading dot; if it doesn't, this function
  will provide it.

  It is an error if FILENAME or EXTENSION is empty, or if FILENAME
  is in the form of a directory name according to `directory-name-p'.

  See also `file-name-sans-extension'."

Looks OK?

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

From: Damien Cassou <damien <at> cassou.me>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 56809 <at> debbugs.gnu.org
Subject: Re: bug#56809: file-name-with-extension: Improve docstring.
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. I would prefer a version
around the word "concatenate" or similar. Here is another version:

  Concatenate FILENAME without its extension and EXTENSION.

It doesn't say that the result of the concatenation is returned but I'm
fine having it implied.

Your call.

-- 
Damien Cassou

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

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.

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

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

Eli Zaretskii <eliz <at> gnu.org> writes:
>> From: Damien Cassou <damien <at> cassou.me>
>> 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?


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.


> And what do you mean by "will know that FILENAME is not going to be
> modified"?


I meant that reasonably-knowledgeable elisp developers will know that
the content of FILENAME isn't going to change after this function is
executed. As a result, a docstring starting with "Return FILENAME
modified to" will be correctly understood by most developers so you
should take my feedback with a grain of salt. That being said, I like
when things are clear and not subject to wrong interpretations so I
would prefer a different phrasing.


>>   Concatenate FILENAME without its extension and EXTENSION.
> I don't want to say how the function does its job


To me "Concatenate" doesn't say how the function is implemented (which
would be something like "Call `concatenate' to…") but what the user
should expect the result to look like (i.e., "the approximate
concatenation of 2 strings").


> "Concatenate" is also inaccurate, because if EXTENSION lacks the
> leading period, that's not really what's going on there.


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. I think the
misunderstanding here is just because "Concatenate" is an implementation
detail for you (so you expect it to correctly reflect the
implementation) while it is just a user-visible result to me (so I don't
really care if the implementation doesn't really concatenate).


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.

Best

-- 
Damien Cassou

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

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.

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

From: Visuwesh <visuweshm <at> gmail.com>
To: Damien Cassou <damien <at> cassou.me>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 56809 <at> debbugs.gnu.org
Subject: Re: bug#56809: file-name-with-extension: Improve docstring.
Date: Thu, 28 Jul 2022 16:04:21 +0530

[வியாழன் ஜூலை 28, 2022] Damien Cassou wrote:

>> "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. I would prefer a version
> around the word "concatenate" or similar. Here is another version:
>
>   Concatenate FILENAME without its extension and EXTENSION.

I find this confusing.  Eli's version looks better (the other one which
mentions basename is no good either).

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

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

Eli Zaretskii <eliz <at> gnu.org> writes:
> Well, the "return" part was supposed to prevent such an
> interpretation.  Moreover, that sentence is just the summary.

Feel free to merge your patch Eli, it's great. I don't want us to keep
discussing on such a tiny detail.

Thank you.

-- 
Damien Cassou

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

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

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

> From: Damien Cassou <damien <at> cassou.me>
> Cc: 56809 <at> debbugs.gnu.org
> Date: Thu, 28 Jul 2022 14:01:56 +0200
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> > Well, the "return" part was supposed to prevent such an
> > interpretation.  Moreover, that sentence is just the summary.
> 
> Feel free to merge your patch Eli, it's great. I don't want us to keep
> discussing on such a tiny detail.

I already merged it to the emacs-28 (a.k.a. "release") branch.  It
will be merged to master soon enough.

But if someone can come up with a better wording, mine is not carved
in stone.

Thanks, closing.

Previous Next

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