From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Andy Moreton Newsgroups: gmane.emacs.devel Subject: Re: Opaque objects and Emacs documentation Date: Fri, 24 Jul 2020 00:40:38 +0100 Message-ID: <86blk5dcll.fsf@gmail.com> 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> <865zadhl1f.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="39392"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (windows-nt) To: emacs-devel@gnu.org Cancel-Lock: sha1:5tnqKs0Aixx7NZghdDQztLclrBA= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Jul 24 01:41:32 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 1jykqC-000ABB-7W for ged-emacs-devel@m.gmane-mx.org; Fri, 24 Jul 2020 01:41:32 +0200 Original-Received: from localhost ([::1]:57438 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jykqB-0005zq-6k for ged-emacs-devel@m.gmane-mx.org; Thu, 23 Jul 2020 19:41:31 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:44552) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jykpU-0005ZU-HP for emacs-devel@gnu.org; Thu, 23 Jul 2020 19:40:49 -0400 Original-Received: from static.214.254.202.116.clients.your-server.de ([116.202.254.214]:40200 helo=ciao.gmane.io) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jykpT-0001y4-0z for emacs-devel@gnu.org; Thu, 23 Jul 2020 19:40:48 -0400 Original-Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1jykpP-0009Pc-Cz for emacs-devel@gnu.org; Fri, 24 Jul 2020 01:40:43 +0200 X-Injected-Via-Gmane: http://gmane.org/ Received-SPF: pass client-ip=116.202.254.214; envelope-from=ged-emacs-devel@m.gmane-mx.org; helo=ciao.gmane.io X-detected-operating-system: by eggs.gnu.org: First seen = 2020/07/23 17:55:47 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: 20 X-Spam_score: 2.0 X-Spam_bar: ++ X-Spam_report: (2.0 / 5.0 requ) BAYES_00=-1.9, DKIM_ADSP_CUSTOM_MED=0.001, FORGED_GMAIL_RCVD=1, FREEMAIL_FORGED_FROMDOMAIN=1, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=1, NML_ADSP_CUSTOM_MED=0.9, 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:253172 Archived-At: On Fri 24 Jul 2020, Andy Moreton wrote: > On Fri 17 Jul 2020, Stefan Monnier wrote: > >>> Basically, you are saying that in your opinion this is as it should >>> be, and cannot be helped. >>> >>> Which I think is against long-time Emacs tradition for documenting its >>> interfaces, and by that facilitating extensibility. It is IMO wrong >>> to fill Emacs application levels with opaque objects which cannot be >>> usefully described; they should be a rare exception, but definitely >>> not the rule. >> >> I believe in this specific case, the issue is that the shape can and >> will change and not only over time. The only thing defined is an >> interface and any code which relies on more than this interface >> (e.g. a function which relies on completion-tables being lists of >> strings) will break sooner or later. >> >> Of course, that doesn't prevent the doc from giving *examples* to show >> the intended behavior. > > I have read this (rather long) thread, and its discussion of all kinds > of low level detail, but it seems the bigger picture is missing. > > Documentation is needed for three distinct audiences: > a) Emacs users > b) Developers adding new methods to provide a new project implementation > which conform to the project API (genric functions) > c) Developers extending the project.el infrastructure. > This is already covered by the commentry in the code (I hope). > > Taking the first two cases in turn: > > a) Users: > Currently there is no documentation that I can see in the manuals for > the project feature for users. As an ordinary user, it is not clear what > problem project.el solves, or how it helps users with their work. Having sent this, I then found that there is a "Working with Projects" section in the manual, but which is not easily found from the top level and is not indexed so it can be found by looking for "project". AndyM