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: Sun, 19 Jul 2020 17:48:16 +0300 Message-ID: <83tuy3h87j.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> <835zamjsvk.fsf@gnu.org> <831rlajock.fsf@gnu.org> <1fcdc463-b3ab-2d32-31d7-904783ae0d81@yandex.ru> <83y2nii6sk.fsf@gnu.org> <750ecd90-0f89-5040-f737-2d8c1b8f01c9@yandex.ru> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="16893"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org, npostavs@gmail.com, dgutov@yandex.ru To: rms@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Jul 19 16:49:11 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 1jxAcp-0004CR-Dj for ged-emacs-devel@m.gmane-mx.org; Sun, 19 Jul 2020 16:49:11 +0200 Original-Received: from localhost ([::1]:44084 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jxAco-0001MZ-Fg for ged-emacs-devel@m.gmane-mx.org; Sun, 19 Jul 2020 10:49:10 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:41330) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jxAcB-0000wH-5S for emacs-devel@gnu.org; Sun, 19 Jul 2020 10:48:31 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:45566) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jxAcA-00069F-Of; Sun, 19 Jul 2020 10:48:30 -0400 Original-Received: from [176.228.60.248] (port=1295 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jxAc3-0002P3-NC; Sun, 19 Jul 2020 10:48:24 -0400 In-Reply-To: (message from Richard Stallman on Sat, 18 Jul 2020 22:27:22 -0400) 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:253101 Archived-At: > From: Richard Stallman > Cc: eliz@gnu.org, npostavs@gmail.com, emacs-devel@gnu.org > Date: Sat, 18 Jul 2020 22:27:22 -0400 > > > > We define an accessor defsubst for each of the data it contains. We > > > document its meaning. We define a constructor function, and document > > > the meaning of each argument. We manipulate them always through those > > > functions. Voilà! > > > > > > The subsctructure is clearly shown and yet changing it later is painless. > > > This is pretty much what I'm doing here. > > > Only a little more complex, because there are multiple data types that > > implement the same interface. > > Eli, do you think the difference is significant? I'm probably missing something, because I don't even see the similarity. Let me explain. What you, Richard, describe is a paradigm we use in several places in Emacs. One example is the POSITION object originally used for describing mouse clicks. Another example is ispell.el's ispell-dictionary-alist. Yet another example is the window-configuration object manipulated by the likes of current-window-configuration and set-window-configuration. In these and other similar examples, we do use defsubst-type accessors to the fields or slots of the object. But we also have the following important traits of the respective objects: . a way of creating an object of that type . a predicate to test whether an arbitrary Lisp value is an object of that type . a function to compare two objects of this type Some of the objects (the first 2 examples above) have their Lisp structure completely documented, in which case the predicate and the comparison functions are not strictly needed (but we still provide them, at least in some cases). When the structure is not documented, the predicate and the comparison functions are IMO a necessity, and there should be either an exhaustive set of accessors for the public fields of the object, or at least a documented list of those fields and how to access them. Taken together, these measures present a useful, usable, and fairly complete description of an abstraction. I can see none of that in project.el regarding the "project instance" abstraction. Not even a description of what a "project instance" is, conceptually, or what it entails, neither in terms of the "outside world" (i.e. the domain of its applicability), nor in terms of the Lisp implementation. And I can only guess what is considered the analogy of the accessors you were alluding to, because it isn't documented, either. (Or maybe the idea is that none of the project's fields are public? but then what is project-root about?) So I don't see how these two techniques can be usefully compared, let alone proclaimed "pretty much" the same. The reason we were given for this lack of crucial documentation in project.el is the desire to leave the API open to extensions. IOW, if, for example, we say today that a project entails a root directory, a collection of files in that directory and its subdirectories, and optionally a set of external tools, such as a VCS, to provide some project-related services, then it will make it harder to add in the future projects of a very different kind. Which is a valid concern, and the reason I started this thread. Because having user commands that allude to "project instance" without even a minimal explanation of what that is makes our documentation of such commands almost useless, and the question that bothers me is how to keep the quality of our documentation at its usual high level while using these or similar design and implementation patterns. Bottom line: unless I'm missing something important, I think the difference is significant, and downplaying it is not a good way of coming up with useful solutions for this important issue.