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: Wed, 22 Jul 2020 17:28:42 +0300 Message-ID: <83imeffwth.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> <837duxgcmw.fsf@gnu.org> <83wo2wfytr.fsf@gnu.org> <70c95ed1-cf68-32c6-49a9-6ed67f20b4c9@yandex.ru> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="16381"; 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 Wed Jul 22 16:29:24 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 1jyFkK-00047y-CG for ged-emacs-devel@m.gmane-mx.org; Wed, 22 Jul 2020 16:29:24 +0200 Original-Received: from localhost ([::1]:58146 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jyFkJ-0004ib-FW for ged-emacs-devel@m.gmane-mx.org; Wed, 22 Jul 2020 10:29:23 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:56864) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jyFjq-0004J7-Oo for emacs-devel@gnu.org; Wed, 22 Jul 2020 10:28:54 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:50122) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jyFjq-0001iC-Bi; Wed, 22 Jul 2020 10:28:54 -0400 Original-Received: from [176.228.60.248] (port=3687 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jyFjg-00056D-AG; Wed, 22 Jul 2020 10:28:45 -0400 In-Reply-To: <70c95ed1-cf68-32c6-49a9-6ed67f20b4c9@yandex.ru> (message from Dmitry Gutov on Wed, 22 Jul 2020 00:31:04 +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:253158 Archived-At: > Cc: rms@gnu.org, emacs-devel@gnu.org > From: Dmitry Gutov > Date: Wed, 22 Jul 2020 00:31:04 +0300 > > >> If you say that, could you give an example of something that *would* be > >> an impediment to extensibility? > > > > What you said: describing what generics returns, or what > > project-current returns in general. > > No, describing "in general" is good. What is bad is describing "in > particular" when a function is "general" and can return values that are > different from the examples. project-current is "general". That's because "general" is overloaded, and you understand it in a sense different from the one in which I used it. Just drop "in general" from what I wrote, and you will have a much better approximation to what I meant. > And speaking of "transient", it's not helpful to say it returns a cons > (transient . root) because that doesn't say anything about the project > behavior anyway (which is the important part). A backend that receives such an object will need to be prepared for it. > > If those are the rules of the game, yes. IOW, if it's not okay to > > describe the possible forms of the object in the doc string of > > project-find-functions, but okay to describe them in the individual > > doc strings of each hook that can be put there, then it could be an > > acceptable compromise, at least from my POV. > > Very well. The "transient" project is not on the hook, though. Yes, but the code which returns it is a kind of "default implementation" for bootstrapping projects. So it is definitely in the same class of objects as the vc project. > >> Right. But there won't be any third-party callers of project-try-vc, > >> this function's only purpose is to be inside project-find-functions. > > > > I'm thinking about additional "authors" who'd like to add > > functionality to existing project backends. > > They won't call it either. If they do, the function is likely to have > changed significantly from its current state. Even if they don't call it (and I'm unconvinced), they will need to deal with the return value, so some documentation about it will be useful. > >> No disagreement there, as long as we're talking about public functions. > > > > Are we still under the rule that any function without 2 dashes in its > > name is public? If so, then I think we have only discussed public > > functions in this and related threads. > > OK, I have a question then. Does every built-in member of a public hook > need to be public? The main point here is that the particular types of objects the existing backends produce should be documented somewhere.