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: Opaque objects and Emacs documentation Date: Fri, 17 Jul 2020 17:56:57 +0300 Message-ID: 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> <83wo32i5lu.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="22593"; 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: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Jul 17 16:57:36 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 1jwRns-0005nF-4a for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 16:57:36 +0200 Original-Received: from localhost ([::1]:44478 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwRnr-0000HH-62 for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 10:57:35 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:59942) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwRnL-0008Ir-G4 for emacs-devel@gnu.org; Fri, 17 Jul 2020 10:57:03 -0400 Original-Received: from mail-wm1-x32f.google.com ([2a00:1450:4864:20::32f]:54474) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jwRnJ-0007kL-GT; Fri, 17 Jul 2020 10:57:03 -0400 Original-Received: by mail-wm1-x32f.google.com with SMTP id o8so15273301wmh.4; Fri, 17 Jul 2020 07:57:00 -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=0XRowrgvhrtFGMp7WjJFVspenN73I9QQJYxNyxpdtxA=; b=XQfwtoKxQwJWrpbi/qpeUVwCZsVcx69tvLwu2bo7pI4HxeIe+2tFpmySjablql0SYp 8LfNrsSCD3A5Sfj9pUm8xiPZYBbE3i2OvccftngiuSK7x4oYDB1Vof07uqd2XVlfPdRQ IdaQo3HG0iPPcgurGd+v4rpIqaZh0ySs4Fmq8I/AixFPQpfaxlrxAT8uSHYYbxZB+ydI /QsNGSmJHZ7A5xgcaFPIgnoeA1HsSxCdDpNcAYfngXmulBXgwenGkuycErTklgtWpvHO LUtem2o5YKa9zGjik0AaQ8qs5VYso1bt+cI1lie8h6skjP2/lJVAqzLKJIBuGEp3v07M Xh1Q== 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=0XRowrgvhrtFGMp7WjJFVspenN73I9QQJYxNyxpdtxA=; b=Wc+FNETr7DTxlC5mrCqF856Yr2bZelsoIpg0CedFoTHZkDR15602HnFa+hi8tT3BTI Amj+zErwOryqjVHJ7VcziT0Zx9c/Nk8cMNX5Ssg3lTTlnU6b/4Aptpqak9ObmUnXteG7 RYvmqIqtlgu/ePrs3Yi49WlI22eIgw1ZoN3XuzayVggiwVWyQ2Bmlcai55YIg6VLZH74 ACFIN0MmIone2J91bhZzcvHxrdI4K+2C5x7bYuFGplfMr0lAbhbfwHnFTbpjCQR0X7Kr OTCb3xSo9V6/Gc1A71/m/37nxndzn7hXg2pb/a+z+ToB+sCiulscZXYF6yedrCWsFhWO OdBw== X-Gm-Message-State: AOAM531tqtsziFDOto6RmW60GvT75urO+RrOvf//9kSjVqt5A/2OM/G/ ndC6zg926ydS2slNSppdM0tR233N X-Google-Smtp-Source: ABdhPJy1MAdFUhOrVT+T2OKvUqg0HclCYAg3nq8HmXFKHnJxndnAOlUXSKWOCt6FQ7SBSDZ2quOm7g== X-Received: by 2002:a1c:720e:: with SMTP id n14mr10329862wmc.144.1594997819191; Fri, 17 Jul 2020 07:56:59 -0700 (PDT) Original-Received: from [192.168.0.6] ([109.110.245.170]) by smtp.googlemail.com with ESMTPSA id u23sm15909660wru.94.2020.07.17.07.56.57 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Fri, 17 Jul 2020 07:56:58 -0700 (PDT) In-Reply-To: <83wo32i5lu.fsf@gnu.org> Content-Language: en-US Received-SPF: pass client-ip=2a00:1450:4864:20::32f; envelope-from=raaahh@gmail.com; helo=mail-wm1-x32f.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:253025 Archived-At: On 17.07.2020 17:22, Eli Zaretskii wrote: > That wasn't the issue. The issue is whether we should use these > techniques in a way that makes it hard or impossible to document our > functions and commands. Even if technically this is the best design > (and I don't yet see why this should be so, nor see any arguments > presented to justify that), we may decide that the price is too heavy. I can hardly understand how we might choose to reject the possibility to implement certain useful features only because return values of some functions become more difficult to document. >> The use of cons cells or some other structures, is a choice, basically >> arbitrary, that can change at will. That is another reason why I don't >> like to see the low-level description in the docstring of project-current. > > As was already written several times, internal implementation details > can be documented without any real impediment of future development. In an appropriate place. Say, the "internals" documentation, wherever it may reside. > So this argument is invalid. Of course. >>> I tried to find one, but couldn't. If someone wants to propose a way, >>> I'm all ears. I wrote those comments which started this thread >>> because it surprised me how difficult it was to try to keep the >>> limitations you impose on what should and what shouldn't be divulged, >>> and yet produce useful documentation of what the various public >>> functions do. In all my 40 years of experience with Emacs, I have >>> never bumped into such a brick wall, with no way around it. >> >> I'm saying it's nothing new: completion tables, for instance, have been >> quite as abstract. > > That one bad example exist doesn't mean we want others. You seem to be on a crusade against abstraction. Never mind that it is the only way to provide features with strong extensibility. >> But for some reason you are fine with docstrings that say "ARG is a >> completion table", or "returns a completion table"? > > Who said I was fine with them? Rome wasn't built in a day. And Carthage must be destroyed, apparently. >> Those are not examples of "developing the package". Those are examples >> of using it. > > Consuming the package's API and adding backends is development of > project.el. No, it isn't. It's not development of the API, or of the built-in backends. > (It is also "using" it, but not on the user level, so > saying that is "using" just muddies the waters, but doesn't affect the > main issue in any way.) If the presence of user-level commands inside project.el confuses you, we can split them into a different file. >>>> The problem here is that even if you document a particular value, it's >>>> _not useful_. It doesn't show you what you can or should do with it. >>> >>> It was very useful for me, and so I presume it could be useful for >>> others. >> >> It has been useful to you to find an answer to a minor question: "how >> projects are compared, which projects are equal?". Which is not >> something most people will even think about. > > Why not? Of course they will. That has never come up in several years. > Besides, the question about what exactly is a "project instance" is > relevant in many places in the package, just look how many doc strings > mention that phrase. Saying that is a cons (and even giving an example), does nothing to address that question. This seems to be the main issue you fail to understand here. >> And even answering that question for the project-vc case doesn't give >> you a general answer. I don't see how you are content with only having >> that answer for a special case anyway. > > That's the only case that we have for now, so it's highly relevant and > useful. Two built-in cases. One case in Stefan's backend which you have never seen. Some backends out there, either existing or future ones. But you need to be able to reason about all of them. >> Perhaps if someone else said "I wanted to do a (valid thing X), couldn't >> understand how to do it, and this piece of information would have made >> it easier"? >> >> No such declarations so far. > > Since when we write documentation only when someone asks a question? You are refuting something I haven't said. > Documentation is supposed to be proactive, it should answer the > important questions before they are asked. Exactly. The important ones. >>> Documentation should strive to serve different ways of studying and >>> developing Emacs, not just a single way that you personally think is >>> The (only) Right Thing. >> >> I already said you can add code comments. Preferably somewhere which is >> not the main entry point of the API. > > I'm sure you understand how low is my motivation to do any work on > documenting project.el. Whatever your motivation is, saying I object to any and all documentation is false. > Look what happened last time: I improved > several doc strings, and suddenly I have a dispute that lasts for a > month, I accepted your multiple edits, and changed a couple of functions and descriptions myself to better support your personal goals. And I removed a couple of sentences you wrote. Which you have been unable to leave alone, or accept my perspective. > and ends up accusing me in all the sins on Earth, including > that I cause contributors to flee and don't understand the code I'm > reading. I'm only human, and have a busy schedule; unpleasant jobs > get pushed back and delayed. There is no hurry. >>> Once again: concealing information because someone could be silly >>> enough to misuse it punishes many valid uses on behalf of a few >>> invalid ones. >> >> Which valid uses, though? > > Any and all of them. That's vague. >> And even when writing documentation for professional programmers, it is >> always considered a good taste to structure it so that it encourages >> writing good code, and discourages writing bad one. > > We encourage writing good code, but not through hiding important > information. Having private/undocumented functions and variables is a common practice even in our project.