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: Opaque objects and Emacs documentation Date: Fri, 17 Jul 2020 17:22:21 +0300 Message-ID: <83wo32i5lu.fsf@gnu.org> 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> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="7562"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Jul 17 16:23:22 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 1jwRGj-0001q9-8X for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 16:23:21 +0200 Original-Received: from localhost ([::1]:60456 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwRGi-0006VO-Bb for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 10:23:20 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:51110) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwRFy-0005qs-Rf for emacs-devel@gnu.org; Fri, 17 Jul 2020 10:22:34 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:54280) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwRFy-0000ET-If; Fri, 17 Jul 2020 10:22:34 -0400 Original-Received: from [176.228.60.248] (port=3571 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jwRFx-0004Gn-Tb; Fri, 17 Jul 2020 10:22:34 -0400 In-Reply-To: (message from Dmitry Gutov on Fri, 17 Jul 2020 16:42:55 +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:253022 Archived-At: > Cc: emacs-devel@gnu.org > From: Dmitry Gutov > Date: Fri, 17 Jul 2020 16:42:55 +0300 > > >> It shouldn't come as a surprise that I think there is no better > >> technological choice. Otherwise I would have used it. > > > > ??? You are saying that the _only_ way to design project.el is to use > > generics at that high level? Just because sometimes a "project > > instance" is a cons cell and sometimes some other Lisp structure? I'm > > surprised to hear that. > > This logic is backwards. The generics are here because we make good use > of them. 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. > 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. So this argument is invalid. > > 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. > 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. > > Later it became apparent that you are doing this on purpose, because > > you have decided that certain directions of developing the package > > should be made as hard as possible, > > That is an unfair misstatement of my words. I provided the URL for your words, so that everyone will be able to make their own minds, in case I've indeed misstated them. > > https://lists.gnu.org/archive/html/emacs-devel/2020-07/msg00288.html > > > > especially under "Here are things we want third-party code to be able > > to do" and "Here are, on the other hand, things that people generally > > shouldn't do". Again, I'm interested to know how many of us here > > share those views. > > 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. (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.) > >> 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. 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. > 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. > > Even if you think it is not useful for you, the fact that > > fellow developers tell you the contrary should be a reason to revisit > > your views, and maybe allow for other views as well, even if you > > disagree. > > 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? Documentation is supposed to be proactive, it should answer the important questions before they are asked. > > 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. Look what happened last time: I improved several doc strings, and suddenly I have a dispute that lasts for a month, 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. > > 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. > > We should treat our users as responsible adults, even > > if some of them aren't. Those who aren't will eventually be amply > > punished, or will recognize their mistakes and get their act together. > > Our users are not all "responsible adults", or to put it differently, > are not all professional programmers. Even even those who are, are at > very different levels of skill. That's exactly the crux of our disagreement, right there. I don't agree with such paternalistic views of our contributors and users. > 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.