unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
From: Eli Zaretskii <eliz@gnu.org>
To: Damien Cassou <damien@cassou.me>
Cc: 56809@debbugs.gnu.org
Subject: bug#56809: file-name-with-extension: Improve docstring.
Date: Thu, 28 Jul 2022 11:57:25 +0300	[thread overview]
Message-ID: <837d3xaa2y.fsf@gnu.org> (raw)
In-Reply-To: <87bkt98wju.fsf@cassou.me> (message from Damien Cassou on Thu, 28 Jul 2022 10:35:01 +0200)

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





  reply	other threads:[~2022-07-28  8:57 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-07-28  6:31 bug#56809: file-name-with-extension: Improve docstring Damien Cassou
2022-07-28  7:49 ` Eli Zaretskii
2022-07-28  8:35   ` Damien Cassou
2022-07-28  8:57     ` Eli Zaretskii [this message]
2022-07-28  9:32       ` Damien Cassou
2022-07-28  9:40         ` Eli Zaretskii
2022-07-28 12:01           ` Damien Cassou
2022-07-28 13:34             ` Eli Zaretskii
2022-07-28 10:34     ` Visuwesh

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.gnu.org/software/emacs/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=837d3xaa2y.fsf@gnu.org \
    --to=eliz@gnu.org \
    --cc=56809@debbugs.gnu.org \
    --cc=damien@cassou.me \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).