From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Gregory Heytings via "Emacs development discussions." Newsgroups: gmane.emacs.devel Subject: Re: master 1e3b0f2: Improve doc strings of project.el Date: Mon, 13 Jul 2020 07:52:57 +0000 Message-ID: References: <87bllfqj82.fsf@warpmail.net> <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> <455BA940-0BFF-4229-A60D-D33A2FF3385B@gnu.org> Reply-To: Gregory Heytings Mime-Version: 1.0 Content-Type: text/plain; format=flowed; charset=US-ASCII Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="17603"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Alpine 2.21 (NEB 202 2017-01-01) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Jul 13 09:54:01 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 1jutHl-0004Rq-10 for ged-emacs-devel@m.gmane-mx.org; Mon, 13 Jul 2020 09:54:01 +0200 Original-Received: from localhost ([::1]:60718 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jutHk-0008TN-3o for ged-emacs-devel@m.gmane-mx.org; Mon, 13 Jul 2020 03:54:00 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:36284) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jutH5-0007q3-Nh for emacs-devel@gnu.org; Mon, 13 Jul 2020 03:53:19 -0400 Original-Received: from mx.sdf.org ([205.166.94.24]:62556) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jutH3-0002DR-Jy for emacs-devel@gnu.org; Mon, 13 Jul 2020 03:53:19 -0400 Original-Received: from sdf.org (IDENT:ghe@faeroes.freeshell.org [205.166.94.9]) by mx.sdf.org (8.15.2/8.14.5) with ESMTPS id 06D7r0sn020564 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256 bits) verified NO); Mon, 13 Jul 2020 07:53:00 GMT Original-Received: (from ghe@localhost) by sdf.org (8.15.2/8.12.8/Submit) id 06D7r0E0011097; Mon, 13 Jul 2020 07:53:00 GMT In-Reply-To: <455BA940-0BFF-4229-A60D-D33A2FF3385B@gnu.org> Received-SPF: pass client-ip=205.166.94.24; envelope-from=ghe@sdf.org; helo=mx.sdf.org X-detected-operating-system: by eggs.gnu.org: First seen = 2020/07/13 03:11:38 X-ACL-Warn: Detected OS = ??? X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action 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:252904 Archived-At: > >> I might be wrong, but I think Dmitry's viewpoint is that if he >> documents X, then X becomes part of the API. Other developers will (or >> might) use X in their code, and he would not be completely free to >> change X anymore. He would have to keep X in a number of future >> versions of his code, document X as being obsolete for a while, create >> Y in parallel, and only later remove X from his code. > > I tried to explain why these fears have no basis: if we clearly say that > some details are subject to change without notice, we can change them > when we need to. > > IOW, doing that does NOT make these details part of the public API which > we promise shall remain stable. > I might be wrong, but in that case I think Dmitry's viewpoint is that this information should not be placed in the doc strings, but in the comments in the source file. Again, I'm not Dmitry, and this does not mean I agree with him. Gregory