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: master 1e3b0f2: Improve doc strings of project.el Date: Sun, 12 Jul 2020 17:47:51 +0300 Message-ID: <83a704okmg.fsf@gnu.org> References: <87bllfqj82.fsf@warpmail.net> <83wo42w83e.fsf@gnu.org> <6762abf5-71c1-aa54-1bac-d4c90c20870b@yandex.ru> <831rmavsuq.fsf@gnu.org> <83a70wv4mj.fsf@gnu.org> <5542db0c-cc0d-2743-87ae-7728a0cc94bb@yandex.ru> <83ftaf2rj2.fsf@gnu.org> <43a8f8d4-83fb-f012-8e1d-c1a618b0ef59@yandex.ru> <83mu4m0vub.fsf@gnu.org> <44f2f1f4-ae34-f0bf-b153-f33b8ee6069f@yandex.ru> <83mu4fvjh3.fsf@gnu.org> <7c2e93d4-8d86-bbbb-77a0-bf5d73051907@yandex.ru> <83imf2t4w4.fsf@gnu.org> <95fd893e-0da5-4cdc-a3e8-3c22af750aae@yandex.ru> <837dvfs6wg.fsf@gnu.org> <8bc1f381-248f-5cee-c3c6-a29d411a2f74@yandex.ru> <837dvbphs0.fsf@gnu.org> <83365zp78d.fsf@gnu.org> <831rlipmgg.fsf@gnu.org> <83lfjqnsa6.fsf@gnu.org> <294212ed-5a6e-0a7f-e1c2-97e917f1e6e1@yandex.ru> <83eepgomts.fsf@gnu.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="33378"; mail-complaints-to="usenet@ciao.gmane.io" Cc: philip@warpmail.net, theo@thornhill.no, emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Jul 12 16:48:33 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 1judHM-0008as-LN for ged-emacs-devel@m.gmane-mx.org; Sun, 12 Jul 2020 16:48:32 +0200 Original-Received: from localhost ([::1]:48424 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1judHL-0001dL-Nl for ged-emacs-devel@m.gmane-mx.org; Sun, 12 Jul 2020 10:48:31 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:54918) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1judGr-0001Cf-U5 for emacs-devel@gnu.org; Sun, 12 Jul 2020 10:48:01 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:42963) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1judGq-000229-HZ; Sun, 12 Jul 2020 10:48:00 -0400 Original-Received: from [176.228.60.248] (port=4940 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1judGp-0000pZ-Op; Sun, 12 Jul 2020 10:48:00 -0400 In-Reply-To: (message from Dmitry Gutov on Sun, 12 Jul 2020 17:16:19 +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:252877 Archived-At: > Cc: theo@thornhill.no, philip@warpmail.net, emacs-devel@gnu.org > From: Dmitry Gutov > Date: Sun, 12 Jul 2020 17:16:19 +0300 > > If I said something is a bad idea, don't go ahead and ignore me. This is > extremely rude. This goes both ways. > Not documenting internal information is a valid choice. It isn't internal. Anyone who wants to use the return value will need to understand its possible form(s). > > But other than that, if someone needs to write code for the VC project > > backend, how can they NOT rely on the form of the object that > > project-try-vc returns? > > Nobody should "write code for the VC project backend" except its > author(s). This is a community project, and everybody is welcome to contribute code to any part of Emacs. Restricting some parts of code to a single person is not a good way of ensuring Emacs's future. > Whatever fuctionality users need to implement, should target the open > API. Which does not depend on the shape of the return value of > project-try-vc. With respect, I disagree, having read the code and having considered how I would implement something related to it. That is the single most important reason why I'm trying to improve the documentation of this package: to make it easier for others to expand and extend it. > > Why should that form, which is important for > > handling any VC project, and is thus part of a public API, be left > > undocumented? > > No, they can't. That information can freely change between versions, so > any reliance on it will create compatibility problems when upgrading. Then let's say that. But concealing the information will not solve the problem, because you cannot conceal it. By not mentioning it and the caveats to go with it we will be punished twice: we will make it harder for people to understand the current code and contribute to it, and we will not make sure they realize that relying on these details is not a good idea. > > You anyway cannot conceal from users information about the innards of > > a Lisp implementation: since the source code is there for everyone to > > see and study, any information you try to conceal will be eventually > > found. All you can do is cause users aggravation by forcing them to > > hunt for that information through many rabbit holes. There are no > > advantages to doing this, only disadvantages. > > If my method of saying "don't rely on this format" is insufficient, > please go ahead and add some more clarifications on that part. But > without documenting this said value format. You cannot usefully tell people to not rely on something without describing that something. And there's the other disadvantage to concealing information: obfuscation of the code. > > More generally, please put yourself in the shoes of someone who wants > > to extend an existing backend, or add a new backend, and try to read > > the documentation through their eyes. > > If they create a new backend, they will read the code of the existing > one. That's not how we encourage extending Emacs. Some minimal documentation is needed before we can in good faith tell users to read the code, and project.el currently falls short of that minimum, IMO. > > They will need to know > > something about the methods they should implement/extend, about which > > ones are and which ones aren't mandatory. > > That is orthogonal to this issue. I don't think it's orthogonal, I think it's all part of the same issue. > > They will need to know > > something about what the project object is or can be, and what minimum > > capabilities should it have. > > Hence the description in my latest commit. It was insufficient. And what we have now, after my changes, is still insufficient, IMO. More work is needed. > >> We have enough trouble with user-defined functions returning (cons 'transient some-root-dir) already. > > > > Which trouble is that? > > People try to customize the root-finding logic this way, and as a result > get a project backend that behaves more slowly than the VC one. And that > affects all of project-* commands that they might like to use. People learn by doing and by making mistakes. It is not a catastrophe if their first attempt is suboptimal. Making the documentation better might be one way of helping them understand how to DTRT. > > And as long as we are talking about this: you mentioned the > > "transient" project without defining what it is. That is not useful. > > I tried to add some minimal explanation of that, and also fixed > > another related omission. > > I would say thank you, but you again documented the return value there. Of course. It's a value that others need to be aware of. > The value is *irrelevant*, and it is, again, internal to the backend. Which backend is that? AFAICT, project-current is backend-agnostic.