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:24:44 +0100 Message-ID: <865zadhl1f.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> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="15709"; 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:GWdNFmJOOfFh6EU2Fn+WciPhBz8= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Jul 24 01:25:27 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 1jykac-000400-6V for ged-emacs-devel@m.gmane-mx.org; Fri, 24 Jul 2020 01:25:26 +0200 Original-Received: from localhost ([::1]:48862 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jykab-0001BA-8r for ged-emacs-devel@m.gmane-mx.org; Thu, 23 Jul 2020 19:25:25 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:41078) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jyka7-0000lm-6l for emacs-devel@gnu.org; Thu, 23 Jul 2020 19:24:55 -0400 Original-Received: from static.214.254.202.116.clients.your-server.de ([116.202.254.214]:53058 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 1jyka5-0008Ba-O7 for emacs-devel@gnu.org; Thu, 23 Jul 2020 19:24:54 -0400 Original-Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1jyka1-0003Hg-M5 for emacs-devel@gnu.org; Fri, 24 Jul 2020 01:24:49 +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:253171 Archived-At: 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. So, please try to extend the docs and the manual for users to state: - what is a project ? - what is the "current project" ? - what is the "transient project" (mentioned in project-current) ? - why is this useful ? How does it help the user ? - what is the interface for users ? - how do users discover this interface ? The doc string for project-root uses the term "current project" without defining it. What is the "current project" ? How is it chosen ? The *help* buffer for project-root docs also shows 3 method implementations, all of which are undocumented: documenting these methods would be more helpful. b) Project backend developers The commentary at the top of project.el describes the project interface fairly loosely. The docs need to describe the interface more precisely: - which functions must be implemented ? - which functions are optional ? - what should a developer consider when choosing which optional functions to implement ? - what is important to consider when implementing these functions ? - if return values are opaque types consumed by other functions, then the docs must clearly state which interface functions consume this data. There has been lengthy discussion about documenting the data types used in the project interface for each implementation. If the interface behaviour is precisely specified, the exact data types are perhaps less important. However it can still be helpful to describe the data types for developers learning how the pieces fit together, even if it is not part of the API contract. -=o0o=- As an ordinary user, project.el requires significant investment of time and effort to discover if it might be useful or not. Most users do not read the elisp sources, and are not necessarily familiar with CL generics. Documenting project.el so that learning process is as short as possible would be a great service to emacs users. AndyM