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 17:16:19 +0300 Message-ID: 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> 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="23699"; 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 16:17:06 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 1jucmv-000633-Sj for ged-emacs-devel@m.gmane-mx.org; Sun, 12 Jul 2020 16:17:05 +0200 Original-Received: from localhost ([::1]:40272 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jucmu-00048J-Ty for ged-emacs-devel@m.gmane-mx.org; Sun, 12 Jul 2020 10:17:04 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:46826) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jucmJ-0003ho-Bz for emacs-devel@gnu.org; Sun, 12 Jul 2020 10:16:27 -0400 Original-Received: from mail-wr1-x430.google.com ([2a00:1450:4864:20::430]:32911) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jucmG-0006VP-QK; Sun, 12 Jul 2020 10:16:26 -0400 Original-Received: by mail-wr1-x430.google.com with SMTP id f18so10342944wrs.0; Sun, 12 Jul 2020 07:16:24 -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=GdQkxdjbsrffl25QOuCQvJQZulMumanCRsX1fq1SaY8=; b=JtXWYK/QW4nz6JmXRB4IFhmBpphi5EtGFIdJartsaiNUpS+VLkWL/hCjcY/Q/MwCkf Ko3gsdb8pSrLoLgdVD3Qb4aNABmTUWxrLux1IHGcA3XWFBrnyz1kZgMN+XBSGucndJoV mBe8G5BS6MqkaSZ2iaSgLSALbhdlT1rBUiffbVfw95jzaXXNxPi9ILytQuyBaoFtq+S9 STrZ7NBBhUvRvpXYo7R+wOCbfewOFBe2vB2UFDvxxeb9l9xY0SfwPZu0gkaKlIdsZRlI BwCUzcy5yisBIx2k4osvIqI3eHdY70+VMNPziRJ20tojL3phTgkMwOr1VJdzc+H4O6FL xyJg== 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=GdQkxdjbsrffl25QOuCQvJQZulMumanCRsX1fq1SaY8=; b=FYs0QqNGyssSTNsd1XCTbdp3EN9nORWRMcNePNHRPYwxFbSqGS+/PxM6NxM300Egcq y052YqjLZ12SJaoBR2QX1QpR8FuEOXWW8d9mo9IdNmUuaKWysETkC01dWMrHibSNnIot QU3G/xz1oIGBCPTkTcgTz0VD7W/axIodcWzil2DdJb4ZFQeYBDqtX+91wMXMKzHrSJdw LCKhg9Q7j1YrTgQ+NXoeJ1fMIjTH+j/c7IpZQbuOemWo8vC73g+2t67O1WTSUY0M4UvT 4YCWqwUphp8yN3s6AKbe7/T1EN4JVp7T7bAOio8I2rxQ4u5t6xH6EkvgZESkwlzfH9q5 Nngw== X-Gm-Message-State: AOAM530N2GSUufs3DHYRjyeh0W06IOSSaLDZmCDUTK4zDcDpSFR78YpM EupZFTrPM7RtYML+bKfKqHkiefax X-Google-Smtp-Source: ABdhPJwmwLEq0yR2+G7EWYopIPXJ6qZnyFad0P4/BfPac7yhRIZOvXkZkBpCbFFZvRb93v0JIHOSEg== X-Received: by 2002:adf:f388:: with SMTP id m8mr78861833wro.338.1594563382144; Sun, 12 Jul 2020 07:16:22 -0700 (PDT) Original-Received: from [192.168.0.3] ([66.205.73.129]) by smtp.googlemail.com with ESMTPSA id l8sm19254987wrq.15.2020.07.12.07.16.20 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sun, 12 Jul 2020 07:16:21 -0700 (PDT) In-Reply-To: <83eepgomts.fsf@gnu.org> Content-Language: en-US Received-SPF: pass client-ip=2a00:1450:4864:20::430; envelope-from=raaahh@gmail.com; helo=mail-wr1-x430.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: 10 X-Spam_score: 1.0 X-Spam_bar: + X-Spam_report: (1.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, FREEMAIL_REPLY=1, 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:252876 Archived-At: On 12.07.2020 17:00, Eli Zaretskii wrote: >> Cc: theo@thornhill.no, philip@warpmail.net, emacs-devel@gnu.org >> From: Dmitry Gutov >> Date: Sun, 12 Jul 2020 03:48:52 +0300 >> >> I've scaled back the explicitness a little: > > I've added back the information you removed. I think the removal was > a mistake, as explained below. And you were asking why I "interpret what you are saying in the worst possible way"? You're behaving like an autocrat. If I said something is a bad idea, don't go ahead and ignore me. This is extremely rude. >> we don't need people to rely on (or try to replicate) the exact format of what project-try-vc returns. > > This is a reason to have _more_ documentation, not _less_. E.g., if > you want the users not to assume or do something, say that explicitly > in the documentation. Or add some other information which will make > it abundantly clear that relying on some detail is a bad idea. Not documenting internal information is a valid choice. > 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). And this backend is maintained strictly within project.el. 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. > 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. > 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. > 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. They're free to copy, but they won't be bitten in the ass when the format changes, because their copy will not. > 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. > 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. > The documentation in project.el > currently has very little to say about this. Various crucial details, > like how project instances are compared, are never really explained, > and only become evident from reading the code. Some extra guidance can be helpful. That doesn't mean your particular choice is the best one. >> 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. > Is it possible that this trouble was caused by > not documenting enough about project.el interfaces and objects? Perhaps. It's undoubtedly (as everywhere) both a documentation and user comprehension problem. I've tried to improve the docs. > 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. The value is *irrelevant*, and it is, again, internal to the backend.