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 11:53:22 +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> Reply-To: emacs-devel@gnu.org, 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="5523"; 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 13:54:23 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 1jwOwY-0001Kn-Gp for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 13:54:22 +0200 Original-Received: from localhost ([::1]:51382 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwOwX-0005Q3-Hn for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 07:54:21 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:60714) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwOw1-0004zf-Oc for emacs-devel@gnu.org; Fri, 17 Jul 2020 07:53:49 -0400 Original-Received: from mx.sdf.org ([205.166.94.24]:54573) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwOvy-0003vd-GQ for emacs-devel@gnu.org; Fri, 17 Jul 2020 07:53:49 -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 06HBrPjc006117 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256 bits) verified NO); Fri, 17 Jul 2020 11:53:25 GMT Original-Received: (from ghe@localhost) by sdf.org (8.15.2/8.12.8/Submit) id 06HBrODZ010909; Fri, 17 Jul 2020 11:53:24 GMT In-Reply-To: <6edffb7d-7708-534f-93ad-bf9180f5e0ed@yandex.ru> 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 07:53:39 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:253011 Archived-At: > >> Which I think is against long-time Emacs tradition for documenting its >> interfaces, and by that facilitating extensibility. It is IMO wrong to >> fill Emacs application levels with opaque objects which cannot be >> usefully described; they should be a rare exception, but definitely not >> the rule. > > The problem here is that even if you document a particular value, it's > _not useful_. It doesn't show you what you can or should do with it. > > The main thing thing the user can do with that value is misuse it, by > relying on its shape in the client code. > 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. 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. Gregory