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: Tue, 21 Jul 2020 17:34:47 +0300 Message-ID: <837duxgcmw.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> <69716ecb-8984-23e0-8b44-322ea3582384@yandex.ru> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="6741"; mail-complaints-to="usenet@ciao.gmane.io" Cc: rms@gnu.org, emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue Jul 21 16:35:56 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 1jxtN6-0001ed-KZ for ged-emacs-devel@m.gmane-mx.org; Tue, 21 Jul 2020 16:35:56 +0200 Original-Received: from localhost ([::1]:34596 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jxtN5-0004xW-Le for ged-emacs-devel@m.gmane-mx.org; Tue, 21 Jul 2020 10:35:55 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:37462) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jxtMA-0003xg-EA for emacs-devel@gnu.org; Tue, 21 Jul 2020 10:34:58 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:57508) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jxtMA-0005Tk-0W; Tue, 21 Jul 2020 10:34:58 -0400 Original-Received: from [176.228.60.248] (port=2765 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jxtM2-0007aB-MZ; Tue, 21 Jul 2020 10:34:51 -0400 In-Reply-To: <69716ecb-8984-23e0-8b44-322ea3582384@yandex.ru> (message from Dmitry Gutov on Tue, 21 Jul 2020 04:09:18 +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:253134 Archived-At: > Cc: eliz@gnu.org, npostavs@gmail.com, emacs-devel@gnu.org > From: Dmitry Gutov > Date: Tue, 21 Jul 2020 04:09:18 +0300 > > We have a "factory" function (called 'project-current') which > delegates project instance creation to a hook. Which is what makes > it extensible. The only argument is DIRECTORY, meaning the current > directory. The functions in the hook get called in turn, and the > first one that returns non-nil is going to be used. Its return value > must be a "project instance" which satisfies a certain protocol > defined by several cl-generic methods (think "interface" in Java, or > "typeclass" in Haskell, or "protocol" in Clojure, or multimethods > elsewhere). One method is mandatory to be defined for all project > implementations, the rest have default implementations. > > Thanks to the cl-generic infrastructure, the datatype representing > the current project can be almost anything, and the structure of the > fields inside can be arbitrary. This is sorted out by each > individual backend which knows how to access fields inside "project > instances" belonging to it, and which implements the aforementioned > protocol for that instance type. The type of "project" returned by project-current can indeed be anything, but each hook function returns a specific type, or maybe a small set of specific types. So the type returned by each hook could be documented in the doc string of that hook in terms suggested by Richard (or something similar). For example, project-try-vc could have a doc string describing that for the project instance it returns. Similarly, the "transient" project instance returned by project-current itself, when a project doesn't yet exist, is also known, and its structure could be similarly documented without impediment to extensibility. > The two built-in backends use very simple structures (right now: conses like (TYPE-TAG . PROJECT-ROOT)), which is very obvious from their implementations. Whether the structure is obvious from the implementation may or may not be true (and the author of the code is usually not the best judge of that), but doesn't solve the issue at hand, IMO. A good documentation of an interface should allow a developer to write code that uses the interface without looking at the interface's implementation. If it is necessary to consult the implementation, that is an indication of some deficiency in the docs, and we should try to avoid that as much as possible.