From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Richard Stallman Newsgroups: gmane.emacs.devel Subject: Re: master 1e3b0f2: Improve doc strings of project.el Date: Sat, 18 Jul 2020 22:27:26 -0400 Message-ID: References: <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> <20200713075842.GA4332@tuxteam.de> <21b47cbb-d1aa-d875-2944-deebb7583961@yandex.ru> <20200717152702.GA18658@tuxteam.de> <922bca06-3425-6fa3-b184-89942c75e91d@yandex.ru> <20200718090546.GC30436@tuxteam.de> <3ae3a7c3-f8c4-a4de-d8bf-d4d62f8f4c44@yandex.ru> Reply-To: rms@gnu.org Content-Type: text/plain; charset=Utf-8 Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="26670"; mail-complaints-to="usenet@ciao.gmane.io" Cc: tomas@tuxteam.de, emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Jul 19 04:28: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 1jwz3i-0006q4-PQ for ged-emacs-devel@m.gmane-mx.org; Sun, 19 Jul 2020 04:28:10 +0200 Original-Received: from localhost ([::1]:35532 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwz3h-0003ER-Qf for ged-emacs-devel@m.gmane-mx.org; Sat, 18 Jul 2020 22:28:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:50042) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwz33-0002Mn-0K for emacs-devel@gnu.org; Sat, 18 Jul 2020 22:27:29 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:37948) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwz31-0002Lt-V3; Sat, 18 Jul 2020 22:27:27 -0400 Original-Received: from rms by fencepost.gnu.org with local (Exim 4.82) (envelope-from ) id 1jwz30-0002zr-C9; Sat, 18 Jul 2020 22:27:26 -0400 In-Reply-To: <3ae3a7c3-f8c4-a4de-d8bf-d4d62f8f4c44@yandex.ru> (message from Dmitry Gutov on Sat, 18 Jul 2020 22:14:07 +0300) 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:253090 Archived-At: [[[ To any NSA and FBI agents reading my email: please consider ]]] [[[ whether defending the US Constitution against all enemies, ]]] [[[ foreign or domestic, requires you to follow Snowden's example. ]]] A Unix file descriptor is a datatype which is semantically opaque and has a representation which is literally opaque. There is nothing inside it that a user program can make sense of. Once the developer of the user program knows this much, there is nothing more to say about it. The package data structure is a very different case. It is made up of Lisp data structures which any Lisp program, and any Emacs user, could look inside. I gather that package.el provides a complete API of functions to do everything anyone would wish, with this data structure. If so, people and programs invoking package.el don't need to know how that data structure is made up. There is no need to describe it in doc strings. But people working on package.el in the future, and people trying to understand it, do need to know its structure. So it should have comments which explain. (I expect Linux has comments describing the meaning of file descriptor data structures.) We shouldn't wait to document that data structure, because any one of us (and that includes you) might, at any moment, suddenly be unable to continue working on Emacs. With luck, you won't have to stop this year -- but it will surely happen some day. So please help people document this in comments. -- Dr Richard Stallman Chief GNUisance of the GNU Project (https://gnu.org) Founder, Free Software Foundation (https://fsf.org) Internet Hall-of-Famer (https://internethalloffame.org)