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

[Damien Cassou <damien@cassou.me>]

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