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: Sun, 12 Jul 2020 17:00:15 +0300 Message-ID: <83eepgomts.fsf@gnu.org> References: <87bllfqj82.fsf@warpmail.net> <831rmayj55.fsf@gnu.org> <6dc2c2ac-8e17-f044-dc78-8c109f936ad2@yandex.ru> <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> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="39174"; 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 Sun Jul 12 16:01:18 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 1jucXe-000A6o-BK for ged-emacs-devel@m.gmane-mx.org; Sun, 12 Jul 2020 16:01:18 +0200 Original-Received: from localhost ([::1]:58984 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jucXc-0007NI-RW for ged-emacs-devel@m.gmane-mx.org; Sun, 12 Jul 2020 10:01:17 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:44454) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jucWp-0006tf-RI for emacs-devel@gnu.org; Sun, 12 Jul 2020 10:00:27 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:42582) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jucWo-0004lt-2o; Sun, 12 Jul 2020 10:00:26 -0400 Original-Received: from [176.228.60.248] (port=1827 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jucWn-0008WG-9I; Sun, 12 Jul 2020 10:00:25 -0400 In-Reply-To: <294212ed-5a6e-0a7f-e1c2-97e917f1e6e1@yandex.ru> (message from Dmitry Gutov on Sun, 12 Jul 2020 03:48:52 +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:252875 Archived-At: > 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. > 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. 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? Why should that form, which is important for handling any VC project, and is thus part of a public API, be left undocumented? 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. 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. They will need to know something about the methods they should implement/extend, about which ones are and which ones aren't mandatory. They will need to know something about what the project object is or can be, and what minimum capabilities should it have. 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. And on top of that you insist on removing details from the documentation that _is_ available. This makes documentation worse, not better. > We have enough trouble with user-defined functions returning (cons 'transient some-root-dir) already. Which trouble is that? Is it possible that this trouble was caused by not documenting enough about project.el interfaces and objects? 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. Thanks.