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: Mon, 13 Jul 2020 07:40:41 +0300 Message-ID: <83y2nom3hy.fsf@gnu.org> References: <87bllfqj82.fsf@warpmail.net> <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> <837dv8oida.fsf@gnu.org> <834kqcoghk.fsf@gnu.org> <99bb8976-580a-ef8e-6b7d-130c3ca5cb8a@yandex.ru> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="8994"; 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 Mon Jul 13 06:41:26 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 1juqHN-0002GS-QQ for ged-emacs-devel@m.gmane-mx.org; Mon, 13 Jul 2020 06:41:25 +0200 Original-Received: from localhost ([::1]:36642 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1juqHM-0003RT-PM for ged-emacs-devel@m.gmane-mx.org; Mon, 13 Jul 2020 00:41:24 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:58784) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1juqGs-000315-Gw for emacs-devel@gnu.org; Mon, 13 Jul 2020 00:40:54 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:55127) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1juqGq-0003u6-Dq; Mon, 13 Jul 2020 00:40:52 -0400 Original-Received: from [176.228.60.248] (port=4477 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1juqGn-0002oR-BW; Mon, 13 Jul 2020 00:40:51 -0400 In-Reply-To: <99bb8976-580a-ef8e-6b7d-130c3ca5cb8a@yandex.ru> (message from Dmitry Gutov on Mon, 13 Jul 2020 04:51:33 +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:252899 Archived-At: > Cc: philip@warpmail.net, theo@thornhill.no, emacs-devel@gnu.org > From: Dmitry Gutov > Date: Mon, 13 Jul 2020 04:51:33 +0300 > > On 12.07.2020 19:17, Eli Zaretskii wrote: > > > Can we approach this from a different angle, please? Can you tell why > > you are so opposed to having this small piece of information in the > > doc strings? What harm can it do that you consider unacceptable? > > Let's try this again. Sadly, you never answered my questions. I still hope that you do, because I don't understand the staunch objections, to the degree that causes extremely unkind responses, to improve the doc string by saying something that is both simple and correct. Instead of answering my practical questions, which could have led us towards some acceptable compromise, you've elected to reiterate your views, which just makes another round of the same dispute we've been having, without any hope for reconciling the differences. Because it turns out we disagree even more than I thought, on the very principles behind this, see below. Please do consider answering my questions. I think it is important to do that, so that we will be able to usefully discuss similar issues in the future. We disagree about the principles, so the only hope is to find some practical compromise with which we will be able to live. > This information is private (or "internal") similar to when we designate > variables or function private: we don't want people to rely on it > because a) that might lead to wrong decisions, b) that might lead to > breakage because this information is subject to changing at will. For > example, I'm considering turning the whole value into a list (it's > currently a shallow cons) and adding the VC backend symbol to the > project-try-vc's return value as the second element to save some CPU cycles. When the form of the return value changes, we will update the documentation. This kind of thing happens all the time in Emacs development, and is nothing to be afraid of. Especially if you consider some information "private", which means we under no obligation to preserve its form. We even have an "Internals" chapter in the ELisp manual (woefully incomplete, but not because we decided not to tell those missing details). This is why I'm frankly astonished by your opposition to document the return value. Once again: what's the catastrophe in doing that? > Here are things we want third-party code to be able to do: > > - Consume the public project APIs, which are currently limited to > 'project-current' and several generic functions defined for project > instance values, to define new commands or supplement existing ones > (e.g. to query the current project for its root or its list of files). Where is this documented? I don't think I see it. > - Create new project backends. Note that we don't want *everybody* to do > that because creating a well-performing backend is a significant amount > of work (unless the user has very particular needs and works with small > projects). But we want this to be a solid option, and it would be ideal > if, say, a handful of backends become popular someday. To create a > backend, one needs to choose the format of its instance value (which > shouldn't match any of the existing formats), write its > project-find-functions element, and define the project-root override > that dispatches on its instance value. Preferably, also implement > overrides for project-ignores and project-files. Where is it documented what needs to be done for creating a new backend? Again, I don't think I see it documented. > Neither of these options requires knowing the exact format of > project-try-vc's return value, if only to stay away from it. But the > odds of a collision seem very low (and there are ways to reduce them > even further). These are just some of the possible development directions. There are others, no less legitimate ones. In particular, minor improvements to the code, which don't change the overall design and implementation. These and others do require to be aware of the form of the return value, or at least they can be helped by knowing that. Moreover, I'm quite sure that if you try to document the missing pieces mentioned above in a way that is useful for potential contributors, you will find soon enough that the policy of hiding useful information about interfaces, even "internal" ones, works against you: it makes it much harder to say something useful about how the various objects and methods interact or should interact. You will eventually be forced to say "read the code" all the time. Which means the documentation cannot do one of its important jobs: help to understand the code. But more generally, it is not our prerogative to decide for others in what directions they may or may not take the development in the future. This is not our pet project, this is a community project, and any member of the community is welcome to propose changes to any part of Emacs. If the change is useful for the users, and is done cleanly, we welcome and accept such changes -- this is how Emacs was and is being developed for 40 years. It is what brought us where we are today. So I very much object to the policy you describe above, which is that you personally decide up front what kinds of changes are and aren't legitimate, based on some principles that are not necessarily shared by others (certainly aren't documented anywhere in the Emacs contribution-related docs), and then unilaterally implement this rigid policy, right down to the level of the smallest detail in the doc strings. This is an extremely radical and harsh policy, which I don't think ever existed in Emacs, nor do I think it should exist. If accepted, it will IMO harm the Emacs development in the long run. > Here are, on the other hand, things that people generally shouldn't do, > and yet I have seen them done: > > - Extract data from the project instance value directly, instead of > going through e.g. 'project-root'. For instance, writing (cdr > (project-current t)) instead of (project-root (project-current t)). The > former is bad code. > > - Write a new project-find-functions element which returns an instance > value that belongs to a built-in backend (usually, the 'transient' one). > AFAICT, this is usually done by cargo culting, without understanding of > the consequences. See above: I disagree very much with saying flatly that we don't want these. These types of changes are not "verboten" in principle, they should be each one of them judged on its own right, and if done cleanly and efficiently, they are not in any way "wrong". In a Free Software project, you cannot forbid people from trying different development directions, even dangerous ones, you can only warn them about the dangers by documenting them. Which is one more reason for having good, detailed documentation. Refraining from mentioning something because you think it is dangerous is the wrong way, because people are curious and will find what you are trying to hide. When they do, no amount of "I didn't want you to know that, so don't do that" will help, believe me. > Both of these require knowing the exact value formats of project > instances used by built-in backends. Thus, documenting them will > encourage these usages. > > I don't want to prohibit the last option outright, but we shouldn't > leave any impression that it's legitimate either. And most problems that > people try to solve this way (predominantly: customizing project root > markers, AFAIK) should be filed as bug reports/feature requests. As I already said several times, the right way of doing this without throwing the baby with the bathwater is to document the value and then tell this form is subject to change without notice. It is a very simple solution that keeps both goals in our sights without losing any of them. > > I added that piece of information because without it I couldn't wrap > > my head around what the code does, in particular when it tries to > > determine which projects are equal to which. > > But it's the wrong direction. > > I mean, you *can* look at the shape of the instance returned by > project-try-vc (which is trivial to do: evaluate the form > (project-current t) and look at the echo area) If the form of a return value can only be obtained by running the code, it is IMO a clear sign that the documentation fails to do its job. Which is exactly why I decided to document it. > but it doesn't give you any guarantee: after all, we need to make > sure project-switch-to-buffer's behavior makes sense for different > backends, even ones we didn't write. Irrelevant: the information I added was about a single _existing_ backend. If you have proposals how to say something sensible and helpful about others, I'm all ears. > So documenting that one backend's instance format is not a solution. It is a solution for those who want to understand better how the _existing_ code works. Admittedly, it's a small step, but it's better than nothing, and it's a step in the right direction. > Instead, it seems we have to document that said value should uniquely > identify the returned project and be "stable": not change over time or > when fetched from different buffers belonging to the same project. That > also means that the value shouldn't contain any caches inside of it. > > And once we add these requirements, the answer to "which projects are > equal" translates to: > > - The backend is the same, > - The instances describe the same project, but the exact fashion depends > on the backend. As it would be anyway. Of course, none of this is described anywhere in project.el. It isn't even clear what objects are part of the design, what are the requirements from each object, how to establish of some arbitrary Lisp object is "an instance of a project", how to compare them, etc. etc. In sum, the crucial information that is expected from any object system is missing, and potential developers are evidently expected to glean it all by reading the code. How does that make sense, and how is it TRT to refuse improvements of the documentation when what we have is this imperfect situation? > > I reckon if this was > > difficult for me, there will be others who could benefit from having > > that info. > This kind of internal information might be better suited for code > comments. But it is missing from comments as well. It is simply not there. > I'm not sure where you could put this particular bit of > information, where it would both be relevant and yet not obvious from > the nearby code, though. _Any_ place is better than _no_ place. "Not sure where to put" is not the same as "let's not document this".