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 02:22:16 +0100 Message-ID: <86zh7pemgn.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="15928"; 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:HrmcQJzsCtOQmcqSnatxpqVdP0c= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Jul 24 03:23:02 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 1jymQP-00043H-NG for ged-emacs-devel@m.gmane-mx.org; Fri, 24 Jul 2020 03:23:01 +0200 Original-Received: from localhost ([::1]:47838 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jymQO-00075o-P6 for ged-emacs-devel@m.gmane-mx.org; Thu, 23 Jul 2020 21:23:00 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:38238) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jymPt-0006dp-95 for emacs-devel@gnu.org; Thu, 23 Jul 2020 21:22:29 -0400 Original-Received: from static.214.254.202.116.clients.your-server.de ([116.202.254.214]:50832 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 1jymPr-0006aB-QN for emacs-devel@gnu.org; Thu, 23 Jul 2020 21:22:29 -0400 Original-Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1jymPo-0003QY-28 for emacs-devel@gnu.org; Fri, 24 Jul 2020 03:22:24 +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:253175 Archived-At: On Fri 24 Jul 2020, Dmitry Gutov wrote: > On 24.07.2020 02:24, Andy Moreton wrote: > >> 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. > > IME, "ordinary users" don't read the manual. At least, not as the first stop. > But sure, we'll need to add some more to it. Indeed. The index in the manual needs improving so that "i project RET" finds the "Working with Projects" node. >> 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 ? > > Doesn't the Commentary cover most (all?) of the above? The manual does cover most of this. User facing docs need to focus on what the backends can do more than the project.el machinery, so as more backends are added, some of the project.el descripion should probably migrate to the elisp manual (as it is of more interest to developers). > BTW, did you read the latest version of it in master? Yes - belatedly, as I only found the info node after posting my previous message. >> The >> *help* buffer for project-root docs also shows 3 method implementations, >> all of which are undocumented: documenting these methods would be more >> helpful. > > Fair point. > > But would those docs say anything more than > > Return the root directory of a "transient" project > > Return the root directory of a "vcs-backed" project A one-liner to give a sense of what they do is fine: that is still more helpful than a list of entries that all say "undocumented". >> 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. > > I think Commentary covers the above now. Again, the latest version. I read project.el from top of tree before posting: it was not clear what the minimal set of methods that are required, nor what are the constraints on how the implementations should behave. >> 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. > > You might want to try pressing 'C-x p C-h'. A useful entry point, but only once you know it exists! Making things discoverable is important for getting new users up to speed. AndyM