From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.help Subject: Re: Is it ok to sort a list of overlays destructively? Date: Wed, 28 Jul 2021 14:44:13 +0300 Message-ID: <83sfzyu0he.fsf@gnu.org> References: <87h7ggcov1.fsf@mbork.pl> <83bl6nvpcl.fsf@gnu.org> <87czr3ecpc.fsf@mbork.pl> <83wnpbtbsk.fsf@gnu.org> <87bl6ndlb3.fsf@mbork.pl> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="27519"; mail-complaints-to="usenet@ciao.gmane.io" To: help-gnu-emacs@gnu.org Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane-mx.org@gnu.org Wed Jul 28 13:45:02 2021 Return-path: Envelope-to: geh-help-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 1m8hzg-0006tW-96 for geh-help-gnu-emacs@m.gmane-mx.org; Wed, 28 Jul 2021 13:45:00 +0200 Original-Received: from localhost ([::1]:32990 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m8hzf-0000Tj-5m for geh-help-gnu-emacs@m.gmane-mx.org; Wed, 28 Jul 2021 07:44:59 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:54418) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m8hz1-0000Sn-JT for help-gnu-emacs@gnu.org; Wed, 28 Jul 2021 07:44:19 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:51696) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m8hz1-00061j-5v for help-gnu-emacs@gnu.org; Wed, 28 Jul 2021 07:44:19 -0400 Original-Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:2140 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m8hz0-0007gP-Oc for help-gnu-emacs@gnu.org; Wed, 28 Jul 2021 07:44:19 -0400 In-Reply-To: <87bl6ndlb3.fsf@mbork.pl> (message from Marcin Borkowski on Wed, 28 Jul 2021 08:06:24 +0200) X-BeenThere: help-gnu-emacs@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Users list for the GNU Emacs text editor List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "help-gnu-emacs" Xref: news.gmane.io gmane.emacs.help:132142 Archived-At: > From: Marcin Borkowski > Cc: help-gnu-emacs@gnu.org > Date: Wed, 28 Jul 2021 08:06:24 +0200 > > Would it be a good idea to say explicitly in the docstrings of both > functions that their results may be safely modified destructively? If > so, I can file a bug report. My personal opinion is that stating this fact in the doc strings of these APIs alone makes little sense: we have many similar APIs, so will need to say the same for most or all of them, otherwise users will become confused. Basically, you should assume that Emacs protects itself where that is needed, so if it handed you a list or some other data, and nothing in the doc string warns you against doing something with that data, you are free to do that, and if that causes unexpected results, there's either a documentation bug or a code bug that needs to be fixed. That said, if you still feel like filing a bug report, please do; perhaps my is an odd-one-out opinion.