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.devel Subject: Re: master 1e3b0f2: Improve doc strings of project.el Date: Mon, 13 Jul 2020 10:21:17 +0300 Message-ID: <455BA940-0BFF-4229-A60D-D33A2FF3385B@gnu.org> References: <87bllfqj82.fsf@warpmail.net> <83mu4m0vub.fsf@gnu.org> <44f2f1f4-ae34-f0bf-b153-f33b8ee6069f@yandex.ru> <83mu4fvjh3.fsf@gnu.org> <7c2e93d4-8d86-bbbb-77a0-bf5d73051907@yandex.ru> <83imf2t4w4.fsf@gnu.org> <95fd893e-0da5-4cdc-a3e8-3c22af750aae@yandex.ru> <837dvfs6wg.fsf@gnu.org> <8bc1f381-248f-5cee-c3c6-a29d411a2f74@yandex.ru> <837dvbphs0.fsf@gnu.org> <83365zp78d.fsf@gnu.org> <831rlipmgg.fsf@gnu.org> <83lfjqnsa6.fsf@gnu.org> <294212ed-5a6e-0a7f-e1c2-97e917f1e6e1@yandex.ru> <83eepgomts.fsf@gnu.org> <83a704okmg.fsf@gnu.org> <5d59dd9b-0848-691a-615e-c16d2070b92d@yandex.ru> <837dv8oida.fsf@gnu.org> <834kqcoghk.fsf@gnu.org> <99bb8976-580a-ef8e-6b7d-130c3ca5cb8a@yandex.ru> <83y2nom3hy.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="35843"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: K-9 Mail for Android To: Gregory Heytings , "Gregory Heytings via Emacs development discussions." , emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Jul 13 09:22:10 2020 Return-path: Envelope-to: ged-emacs-devel@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 1jusmv-0009Bv-3w for ged-emacs-devel@m.gmane-mx.org; Mon, 13 Jul 2020 09:22:09 +0200 Original-Received: from localhost ([::1]:44782 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jusmu-000612-6E for ged-emacs-devel@m.gmane-mx.org; Mon, 13 Jul 2020 03:22:08 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:58160) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jusmB-00055n-Sb for emacs-devel@gnu.org; Mon, 13 Jul 2020 03:21:23 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:58470) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jusmB-0006e4-8i; Mon, 13 Jul 2020 03:21:23 -0400 Original-Received: from [176.12.222.55] (port=56057 helo=[10.160.127.200]) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1jusm9-0007Z8-SB; Mon, 13 Jul 2020 03:21:22 -0400 In-Reply-To: X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:252903 Archived-At: On July 13, 2020 10:11:21 AM GMT+03:00, "Gregory Heytings via Emacs develop= ment discussions=2E" wrote: >=20 > > > >> This information is private (or "internal") similar to when we=20 > >> designate variables or function private: we don't want people to > rely=20 > >> on it because a) that might lead to wrong decisions, b) that might > lead=20 > >> to breakage because this information is subject to changing at > will=2E=20 > >> For example, I'm considering turning the whole value into a list > (it's=20 > >> currently a shallow cons) and adding the VC backend symbol to the=20 > >> project-try-vc's return value as the second element to save some > CPU=20 > >> cycles=2E > > > > When the form of the return value changes, we will update the=20 > > documentation=2E This kind of thing happens all the time in Emacs=20 > > development, and is nothing to be afraid of=2E Especially if you > consider=20 > > some information "private", which means we under no obligation to=20 > > preserve its form=2E We even have an "Internals" chapter in the ELisp >=20 > > manual (woefully incomplete, but not because we decided not to tell=20 > > those missing details)=2E > > > > This is why I'm frankly astonished by your opposition to document > the=20 > > return value=2E Once again: what's the catastrophe in doing that? > > >=20 > I might be wrong, but I think Dmitry's viewpoint is that if he > documents=20 > X, then X becomes part of the API=2E Other developers will (or might) > use X=20 > in their code, and he would not be completely free to change X > anymore=2E=20 > He would have to keep X in a number of future versions of his code,=20 > document X as being obsolete for a while, create Y in parallel, and > only=20 > later remove X from his code=2E I tried to explain why these fears have no basis: if we clearly say that s= ome details are subject to change without notice, we can change them when w= e need to=2E IOW, doing that does NOT make these details part of the public API which w= e promise shall remain stable=2E