From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel Subject: Re: master 1e3b0f2: Improve doc strings of project.el Date: Sun, 12 Jul 2020 18:08:50 +0300 Message-ID: <5d59dd9b-0848-691a-615e-c16d2070b92d@yandex.ru> 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> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="37816"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0 Cc: philip@warpmail.net, theo@thornhill.no, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Jul 12 17:09:29 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 1judbc-0009jd-TY for ged-emacs-devel@m.gmane-mx.org; Sun, 12 Jul 2020 17:09:29 +0200 Original-Received: from localhost ([::1]:53080 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1judbb-0005Yy-T3 for ged-emacs-devel@m.gmane-mx.org; Sun, 12 Jul 2020 11:09:27 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:58898) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1judb6-00058N-RZ for emacs-devel@gnu.org; Sun, 12 Jul 2020 11:08:56 -0400 Original-Received: from mail-wr1-x435.google.com ([2a00:1450:4864:20::435]:39282) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1judb4-0005Jr-PZ; Sun, 12 Jul 2020 11:08:56 -0400 Original-Received: by mail-wr1-x435.google.com with SMTP id q5so10424318wru.6; Sun, 12 Jul 2020 08:08:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:subject:to:cc:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=svLBm6G8JQAHe5fXvZ4ViMtGytqAZZy8GZAuVPZ0ipg=; b=UDxm4xFCO9gmRBc0z/KaaHYFYPl/66QSSUtjfGh7QOq7Fi+nWIGzIcviJnc1G4CDmv iWbkfV5TBM9bAGwQlz+DMVpRLBe9HCKGLCNSHZuAi0arxaOtwm/rq96bZ0chzg7WhKwI BD2BaecxHrqLpB8OQWnai6A2G4vcRPb6ZD7mdQC5Y+dAt+bPPhtoTOv9LOrhpilKVFRa Q1xj9syVzb/x+2UEK2u7NXNcO9ww5clvLP0bQusafQj92TMNTq+UFiMvngECWHVsNK8t t7Lb20P7h24EzMTEyBkw7vYqpVcdwk2wUDfiUDZ3iy0rgon5S5bnEwTTQAcsqhE+075n 7eJw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:subject:to:cc:references:from:message-id :date:user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=svLBm6G8JQAHe5fXvZ4ViMtGytqAZZy8GZAuVPZ0ipg=; b=hZ5VVJ+7/ZAKanFuWz8lqLxXLzGiw/EVQhKgGTW2SM4nRfYgKsVUwnRCKyOIMLxt+c mcJKr5Tejk8qKnQ7TlafEL5PQWmrwv2pAT+oaQNX+eLGIxZYhMwxDuqlJh9EmwNnpngt D8THAnfOfsibTfocJUJ2pNr38lhOzzZ2VCVFHl6mLMabC75PQXpQ2pk89lsMfPH0SYRA g/+zYUUxb96+ZxKNB73MalDxRWIeyxlVZXz+nZUFTEdfuSEKG2rTsrt068fiSmco48Po cAv7utsh1BmPXR6eMdgHpIBY0evKEpDJFybEUkch4LjYlhbpMPoP6EhCJBLg7DDK3rHP xKpA== X-Gm-Message-State: AOAM531nzJHgLCDYhZb34BFVTZdpa9EjQQxBV7jXf4lcHX8ABfnSyRN4 dOo/pl2ydZXUxx1Mrb2ywf05bln4 X-Google-Smtp-Source: ABdhPJzdkIDM2n/Tsklyd5R78RGyg1jrwEKo9pQQwxTEAO0lDxs/LKNq4eG7GECSOiT7JnT7tZa2lQ== X-Received: by 2002:a5d:66ca:: with SMTP id k10mr64813079wrw.244.1594566532486; Sun, 12 Jul 2020 08:08:52 -0700 (PDT) Original-Received: from [192.168.0.3] ([66.205.73.129]) by smtp.googlemail.com with ESMTPSA id u1sm22944128wrb.78.2020.07.12.08.08.51 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sun, 12 Jul 2020 08:08:51 -0700 (PDT) In-Reply-To: <83a704okmg.fsf@gnu.org> Content-Language: en-US Received-SPF: pass client-ip=2a00:1450:4864:20::435; envelope-from=raaahh@gmail.com; helo=mail-wr1-x435.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: 0 X-Spam_score: 0.0 X-Spam_bar: / X-Spam_report: (0.0 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FORGED_FROMDOMAIN=1, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action 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:252879 Archived-At: On 12.07.2020 17:47, Eli Zaretskii wrote: >> If I said something is a bad idea, don't go ahead and ignore me. This is >> extremely rude. > > This goes both ways. It never does with you. 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. >> 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. >>> 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. Internal information can reside there without being documented, if all of its producers and consumers also reside there. >> 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. 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. So the docstring shouldn't either. You can still ask those questions. >>> 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, There's nothing hard in understanding what the current code returns: you navigate to the function's definition and look at the end. > 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. >> 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. > And there's the other disadvantage to > concealing information: obfuscation of the code. The code is not the issue. >>> 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. You seem to be criticizing something else than what I said. And I never said we don't need documentation. >>> 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. Mentioning (vc . "path/to/root") somehow helps the users know which methods they need to implement? You must be kidding. >>> 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. Of course. On *different* aspects. >>>> 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. Right. >>> 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? The 'transient' backend. 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.