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:11:21 +0000 Message-ID: References: <87bllfqj82.fsf@warpmail.net> <43a8f8d4-83fb-f012-8e1d-c1a618b0ef59@yandex.ru> <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> 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="38496"; 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:14:02 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 1jusf3-0009sA-QW for ged-emacs-devel@m.gmane-mx.org; Mon, 13 Jul 2020 09:14:01 +0200 Original-Received: from localhost ([::1]:36274 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jusf2-0002DV-Rk for ged-emacs-devel@m.gmane-mx.org; Mon, 13 Jul 2020 03:14:00 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:56396) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1juscw-0001Zd-Sl for emacs-devel@gnu.org; Mon, 13 Jul 2020 03:11:50 -0400 Original-Received: from mx.sdf.org ([205.166.94.24]:49495) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1juscu-0005bR-Pq for emacs-devel@gnu.org; Mon, 13 Jul 2020 03:11:50 -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 06D7BOlX017520 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256 bits) verified NO); Mon, 13 Jul 2020 07:11:24 GMT Original-Received: (from ghe@localhost) by sdf.org (8.15.2/8.12.8/Submit) id 06D7BO71006050; Mon, 13 Jul 2020 07:11:24 GMT In-Reply-To: <83y2nom3hy.fsf@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:252902 Archived-At: > >> This information is private (or "internal") similar to when we >> designate variables or function private: we don't want people to rely >> on it because a) that might lead to wrong decisions, b) that might lead >> to breakage because this information is subject to changing at will. >> For example, I'm considering turning the whole value into a list (it's >> currently a shallow cons) and adding the VC backend symbol to the >> project-try-vc's return value as the second element to save some CPU >> cycles. > > When the form of the return value changes, we will update the > documentation. This kind of thing happens all the time in Emacs > development, and is nothing to be afraid of. Especially if you consider > some information "private", which means we under no obligation to > preserve its form. We even have an "Internals" chapter in the ELisp > manual (woefully incomplete, but not because we decided not to tell > those missing details). > > This is why I'm frankly astonished by your opposition to document the > return value. Once again: what's the catastrophe in doing that? > 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. IOW, it is not only a matter of updating the documentation, it is a matter of updating all code that relied on that documentation. (Note that this does NOT mean I agree with Dmitry.) Gregory