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 18:36:33 +0300 Message-ID: <837dv8oida.fsf@gnu.org> References: <87bllfqj82.fsf@warpmail.net> <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> <83a704okmg.fsf@gnu.org> <5d59dd9b-0848-691a-615e-c16d2070b92d@yandex.ru> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="31320"; 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 17:37:37 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 1jue2r-00084U-LM for ged-emacs-devel@m.gmane-mx.org; Sun, 12 Jul 2020 17:37:37 +0200 Original-Received: from localhost ([::1]:58990 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jue2q-0001g7-LS for ged-emacs-devel@m.gmane-mx.org; Sun, 12 Jul 2020 11:37:36 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:37124) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jue20-0001Cr-7A for emacs-devel@gnu.org; Sun, 12 Jul 2020 11:36:44 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:43551) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jue1z-000121-3z; Sun, 12 Jul 2020 11:36:43 -0400 Original-Received: from [176.228.60.248] (port=3936 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jue1x-0002jY-KA; Sun, 12 Jul 2020 11:36:41 -0400 In-Reply-To: <5d59dd9b-0848-691a-615e-c16d2070b92d@yandex.ru> (message from Dmitry Gutov on Sun, 12 Jul 2020 18:08:50 +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:252880 Archived-At: > Cc: theo@thornhill.no, philip@warpmail.net, emacs-devel@gnu.org > From: Dmitry Gutov > Date: Sun, 12 Jul 2020 18:08:50 +0300 > > If I work on parts of Emacs I'm not responsible for, I make doubly sure > to check with authors/maintainers. > > How about you extend me this courtesy? I'm the author and the maintainer > of this package. I do. This longish and frustrating discussion is the best evidence to that. > >> 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). > > Yes, it is. Apparently you don't understand how cl-generic works. Please drop the attitude. > >>> 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. > > Not the person. The place. project-vc lives in project.el. Irrelevant. I meant people other than the author of the code, the person. Those others will need more detailed documentation than what you are prepared to provide. > Internal information can reside there without being documented, if all > of its producers and consumers also reside there. This is a new definition of what is "internal", and I don't agree with it. Our accepted definition is different. > > 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. > > If you had asked me questions like "how do I implement this or that", > none of my answers would have included the format of the return value of > project-try-vc. I know. Which is why I don't think your method of answering such questions is useful enough to be used as basis for good documentation. > > 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, > > There's nothing hard in understanding what the current code returns: you > navigate to the function's definition and look at the end. Documentation exists so that I won't need to follow a chain of several functions to find the answer to a simple question. (And no, just reading the code of project-try-vc is not enough, not unless you know by heart what each one of the functions it calls does and returns.) > > and we will not make sure they realize that relying on these details > > is not a good idea. > > Like I said, if you're not satisfied with how that recommendation is > conveyed, feel free to add clarifications. *Without* giving the example > of said values in the docstrings. I think describing the values returned by public functions is a large part of good documentation, it clarifies quite a lot in a very efficient way (a picture is worth a thousand words). > >> 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 yet, somehow, parents around the world manage to tell their children > not to use swear words without swearing profusely themselves. Sure, it isn't needed, not after the child him/herself swears, which is the trigger for the parents telling them not to. > > And there's the other disadvantage to > > concealing information: obfuscation of the code. > > The code is not the issue. Of course it is! Documentation is a significant aid in understanding the code. > >> 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. > > You seem to be criticizing something else than what I said. I'm criticizing the "they will read the code" part. > And I never said we don't need documentation. I never said you did. > Okay, internal to project.el, if we want to be more precise. > > > AFAICT, project-current is backend-agnostic. > > Except when we want to return some project instance where none were > detected. Which is exactly what the text I added says.