From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Opaque objects and Emacs documentation Date: Fri, 17 Jul 2020 14:14:23 +0300 Message-ID: <835zamjsvk.fsf@gnu.org> 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> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="35388"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Jul 17 13:15:07 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 1jwOKZ-0008u3-5G for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 13:15:07 +0200 Original-Received: from localhost ([::1]:44446 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwOKY-0004IR-3G for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 07:15:06 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:50246) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwOK4-0003rk-LP for emacs-devel@gnu.org; Fri, 17 Jul 2020 07:14:36 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:47430) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwOK4-0008WU-69; Fri, 17 Jul 2020 07:14:36 -0400 Original-Received: from [176.228.60.248] (port=3627 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jwOK3-0004xp-7G; Fri, 17 Jul 2020 07:14:35 -0400 In-Reply-To: <6edffb7d-7708-534f-93ad-bf9180f5e0ed@yandex.ru> (message from Dmitry Gutov on Fri, 17 Jul 2020 13:53:35 +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:253010 Archived-At: > Cc: emacs-devel@gnu.org > From: Dmitry Gutov > Date: Fri, 17 Jul 2020 13:53:35 +0300 > > It shouldn't come as a surprise that I think there is no better > technological choice. Otherwise I would have used it. ??? You are saying that the _only_ way to design project.el is to use generics at that high level? Just because sometimes a "project instance" is a cons cell and sometimes some other Lisp structure? I'm surprised to hear that. > What should help is coming up with a better, consistent way to document > these things. I tried to find one, but couldn't. If someone wants to propose a way, I'm all ears. I wrote those comments which started this thread because it surprised me how difficult it was to try to keep the limitations you impose on what should and what shouldn't be divulged, and yet produce useful documentation of what the various public functions do. In all my 40 years of experience with Emacs, I have never bumped into such a brick wall, with no way around it. Later it became apparent that you are doing this on purpose, because you have decided that certain directions of developing the package should be made as hard as possible, something that I think is completely against the spirit of Emacs development. Readers of this thread are invited to read https://lists.gnu.org/archive/html/emacs-devel/2020-07/msg00288.html especially under "Here are things we want third-party code to be able to do" and "Here are, on the other hand, things that people generally shouldn't do". Again, I'm interested to know how many of us here share those views. > > 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. It was very useful for me, and so I presume it could be useful for others. Even if you think it is not useful for you, the fact that fellow developers tell you the contrary should be a reason to revisit your views, and maybe allow for other views as well, even if you disagree. Documentation should strive to serve different ways of studying and developing Emacs, not just a single way that you personally think is The (only) Right Thing. > The main thing thing the user can do with that value is misuse it, by > relying on its shape in the client code. Once again: concealing information because someone could be silly enough to misuse it punishes many valid uses on behalf of a few invalid ones. We should treat our users as responsible adults, even if some of them aren't. Those who aren't will eventually be amply punished, or will recognize their mistakes and get their act together.