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: Opaque objects and Emacs documentation Date: Fri, 17 Jul 2020 21:55:35 -0400 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> 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="40070"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: emacs-devel@gnu.org, Gregory Heytings Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Jul 18 03:56:28 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 1jwc5U-000AKQ-Gw for ged-emacs-devel@m.gmane-mx.org; Sat, 18 Jul 2020 03:56:28 +0200 Original-Received: from localhost ([::1]:58136 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwc5T-0000IC-IZ for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 21:56:27 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:51304) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwc4n-0007ob-2b for emacs-devel@gnu.org; Fri, 17 Jul 2020 21:55:45 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:39383) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwc4m-0005sP-Q4; Fri, 17 Jul 2020 21:55:44 -0400 Original-Received: from rms by fencepost.gnu.org with local (Exim 4.82) (envelope-from ) id 1jwc4d-0007u8-EW; Fri, 17 Jul 2020 21:55:37 -0400 In-Reply-To: (emacs-devel@gnu.org) 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:253060 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. ]]] > to help all those > who in the future, when you will have moved to something else, will work > on the code you wrote. For them it is definitely very useful to > understand the implementation choices you made, the internal > representations you chose to use, and so forth. In fact, such a > documentation is probably also useful for yourself, if you leave your code > temporarily, and come back to it after a while. Those explanations are very important, but they do not have to be in the doc strings and manuals, If including them in doc strings and manuals is not particularly useful, we put them in comments in the source files. -- 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)