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: Opaque objects and Emacs documentation Date: Fri, 17 Jul 2020 14:26:27 +0000 Message-ID: References: <20200712184908.13140.5739@vcs0.savannah.gnu.org> <20200712184909.BBC61209B1@vcs0.savannah.gnu.org> <7bf4d6ef-c0ec-43dc-ad5d-f6e81422ad90@yandex.ru> <83zh84m5ws.fsf@gnu.org> <3dd1c224-69b2-40af-5b2e-43a310253632@yandex.ru> <83tuybmtxs.fsf@gnu.org> <859f594b-1343-6d26-e1ac-7157c44eb56c@yandex.ru> <83a6zyk4tt.fsf@gnu.org> <6edffb7d-7708-534f-93ad-bf9180f5e0ed@yandex.ru> <57619ed5-49d5-d2a5-f205-8ea722d7f703@yandex.ru> Reply-To: emacs-devel@gnu.org, Gregory Heytings Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII; format=flowed Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="7242"; 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 Fri Jul 17 18:26:03 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 1jwTBS-0001lz-JH for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 18:26:02 +0200 Original-Received: from localhost ([::1]:39688 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwTBR-0001rp-Ir for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 12:26:01 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:34170) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwTAq-0001MD-Qx for emacs-devel@gnu.org; Fri, 17 Jul 2020 12:25:24 -0400 Original-Received: from mx.sdf.org ([205.166.94.24]:59523) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwTAo-0002XF-Re for emacs-devel@gnu.org; Fri, 17 Jul 2020 12:25:24 -0400 Original-Received: from sdf.org (IDENT:smmsp@faeroes.freeshell.org [205.166.94.9]) by mx.sdf.org (8.15.2/8.14.5) with ESMTPS id 06HGP7Yo000107 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256 bits) verified NO); Fri, 17 Jul 2020 16:25:07 GMT Original-Received: (from ghe@localhost) by sdf.org (8.15.2/8.12.8/Submit) id 06HEQUxR019123; Fri, 17 Jul 2020 14:26:30 GMT In-Reply-To: <57619ed5-49d5-d2a5-f205-8ea722d7f703@yandex.ru> Content-ID: 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/17 12:25:21 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:253037 Archived-At: > >> IMO the main goal of writing Emacs documentation (and software >> documentation in general) is not to help its users, but to help all >> those who in the future, when you will have moved to something else, >> will work on the code you wrote. > > So you have never encountered a difference between internal > documentation and public documentation? > Of course I did. But as it happens, this difference does not exist in Emacs. Remember that one of the direct inspirations of Emacs were Lisp machines, in which the user can read and modify almost every piece of code on the fly, from the lowest to the highest level. In such a system, there can be no difference between "internal" and "external" documentation. I understand that it can be difficult to adapt to this way of thinking when one comes from another programming tradition. > > The most valuable documentation is [...] that which describes original > choices, and the reasons for them. Or an overview of how the system > works. We're not discussing either of those options here. > It's one way to document things, but certainly not the only one. I'm not sure I agree that it's the "most valuable" one. When you have to work on code written by someone else, you rarely do so on the highest level, and having a picture of the overall organization is not directly useful. Having a clear and well-written documentation for each function is directly useful. Gregory