From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Damien Cassou Newsgroups: gmane.emacs.bugs Subject: bug#56809: file-name-with-extension: Improve docstring. Date: Thu, 28 Jul 2022 11:32:55 +0200 Message-ID: <878rod8tvc.fsf@cassou.me> References: <87edy5929v.fsf@cassou.me> <83ilnhad8j.fsf@gnu.org> <87bkt98wju.fsf@cassou.me> <837d3xaa2y.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="12300"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 56809@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Jul 28 11:41:39 2022 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1oH01S-000341-Eh for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 28 Jul 2022 11:41:38 +0200 Original-Received: from localhost ([::1]:47698 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oH01R-0002q5-8a for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 28 Jul 2022 05:41:37 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:36932) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oGzu6-0005Yn-5U for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2022 05:34:04 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:39645) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oGzu5-0008LS-SK for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2022 05:34:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oGzu5-0006wb-Oj for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2022 05:34:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Damien Cassou Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 28 Jul 2022 09:34:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 56809 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 56809-submit@debbugs.gnu.org id=B56809.165900078326595 (code B ref 56809); Thu, 28 Jul 2022 09:34:01 +0000 Original-Received: (at 56809) by debbugs.gnu.org; 28 Jul 2022 09:33:03 +0000 Original-Received: from localhost ([127.0.0.1]:57624 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oGzt8-0006ut-Ij for submit@debbugs.gnu.org; Thu, 28 Jul 2022 05:33:02 -0400 Original-Received: from mail.choca.pics ([80.67.172.235]:39526) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oGzt5-0006uN-5X for 56809@debbugs.gnu.org; Thu, 28 Jul 2022 05:33:00 -0400 Original-Received: from localhost (localhost.localdomain [IPv6:::1]) by mail.choca.pics (Postfix) with ESMTP id A903418192DC8; Thu, 28 Jul 2022 11:32:57 +0200 (CEST) Original-Received: from mail.choca.pics ([IPv6:::1]) by localhost (mail.choca.pics [IPv6:::1]) (amavisd-new, port 10032) with ESMTP id 5P8CUmVkq2US; Thu, 28 Jul 2022 11:32:57 +0200 (CEST) Original-Received: from localhost (localhost.localdomain [IPv6:::1]) by mail.choca.pics (Postfix) with ESMTP id ECF9B18192DCC; Thu, 28 Jul 2022 11:32:56 +0200 (CEST) X-Virus-Scanned: amavisd-new at choca.pics Original-Received: from mail.choca.pics ([IPv6:::1]) by localhost (mail.choca.pics [IPv6:::1]) (amavisd-new, port 10026) with ESMTP id 34CR0TCUpdWZ; Thu, 28 Jul 2022 11:32:56 +0200 (CEST) Original-Received: from localhost (240-68-190-109.dsl.ovh.fr [109.190.68.240]) by mail.choca.pics (Postfix) with ESMTPSA id 9F13E18192DC8; Thu, 28 Jul 2022 11:32:56 +0200 (CEST) In-Reply-To: <837d3xaa2y.fsf@gnu.org> X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:238090 Archived-At: Eli Zaretskii writes: >> From: Damien Cassou >> Eli Zaretskii writes: >>> Looks OK? >>=20 >> looks better than my version :-). The only thing I don't really like is >>=20 >>> "Return FILENAME modified to=E2=80=A6 >>=20 >> 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=E2=80=A6") 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 =F0=9F=98=83. I'm sorry I made you loose your time. Best --=20 Damien Cassou "Success is the ability to go from one failure to another without losing enthusiasm." --Winston Churchill