From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel Subject: Re: Opaque objects and Emacs documentation Date: Fri, 24 Jul 2020 03:43:41 +0300 Message-ID: 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; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="20468"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0 To: Andy Moreton , emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Jul 24 02:44:46 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 1jylpO-0005Ej-7U for ged-emacs-devel@m.gmane-mx.org; Fri, 24 Jul 2020 02:44:46 +0200 Original-Received: from localhost ([::1]:40034 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jylpM-0001Cs-WF for ged-emacs-devel@m.gmane-mx.org; Thu, 23 Jul 2020 20:44:45 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:56840) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jyloS-0000nQ-4a for emacs-devel@gnu.org; Thu, 23 Jul 2020 20:43:48 -0400 Original-Received: from mail-wr1-x42c.google.com ([2a00:1450:4864:20::42c]:33236) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jyloQ-0001qS-5q for emacs-devel@gnu.org; Thu, 23 Jul 2020 20:43:47 -0400 Original-Received: by mail-wr1-x42c.google.com with SMTP id f18so6802991wrs.0 for ; Thu, 23 Jul 2020 17:43:45 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:subject:to:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=OhRyJyNifLAxA3kCkzRN8+BgUb0GivsvO14ES/K5qag=; b=jBnU2sji06wvAWXPXKTIOKBbtJuch9siomEyFfVnczaqvvzC7+g/GGlASi9HuQKpbm WtX6BKaDt3EKT3lpC+wCkQ4bBolk1kXCohDhYoHcpmqBEMVbFomeerWh8hllSkDqf5N5 tE9MrIN4LugzzJB2noQI9sIfZxDeFsZrCIfjQUI+Rsjfw+J3Tiy72EOU+TNW1aPgk6nu uZmN5svFFSl/5AmoS2nOjUs5NFxVc+ACVS53KFsAajn/v7q5nTeSy8fHHW9zDRhQ286b 75TYRP4yAWNtpgxv6Us6K8oINGzl5VIDmxwLRggX24lFOUb8TozjgvVIWI6WXeC1AI6Q oXUg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:subject:to:references:from:message-id :date:user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=OhRyJyNifLAxA3kCkzRN8+BgUb0GivsvO14ES/K5qag=; b=kzQz0t4IbWgl7gdD2IXXwbqEVkFzQk2B1yfcKmEg4JZKn/HZDX1xYyw7PZluSSClKI Vqn/hc7Q4X+McVjM+46J/f5aJOVR7Q2f8nJRfwSYyhaaPbh8DVZqxz9m3fPgBkGCZ6p+ RwIIS/qDxGA3/Lr63DQLaJnC/fzFEYlcdo7WV/R+ibpT3RGllYXkjP0Y60hcQ7NQCKDT P7El+ji3InIa2lWJA6m5CqOOhn3+grFRFZH3h4t1H5eFQn7FS55q2fqvvlZwRcM26SDm LQ2FdzOpQwzmYcrHKSa9v1SIgfwndoGFnZFaqcPqcMcfC/S1eAkeegnMexbcxk1dFRw7 YJgg== X-Gm-Message-State: AOAM531OLSMBykSxXACxpxIUfqy1CP3CWZIKLR5eJKSG9gS/axAdt9qO TpYcrm2j6wXVEQkldb/uJnvB8S0D X-Google-Smtp-Source: ABdhPJzjVlvtkTbLmyrA1XBTxiwwOwm2xWQQYS7E47M84evvQHMVmSvLDefQpabU+DDZ48s6e+tiZQ== X-Received: by 2002:adf:e68f:: with SMTP id r15mr6099199wrm.196.1595551423990; Thu, 23 Jul 2020 17:43:43 -0700 (PDT) Original-Received: from [192.168.0.3] ([66.205.73.129]) by smtp.googlemail.com with ESMTPSA id a10sm5513503wrx.15.2020.07.23.17.43.42 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 23 Jul 2020 17:43:42 -0700 (PDT) In-Reply-To: <865zadhl1f.fsf@gmail.com> Content-Language: en-US Received-SPF: pass client-ip=2a00:1450:4864:20::42c; envelope-from=raaahh@gmail.com; helo=mail-wr1-x42c.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: 0 X-Spam_score: 0.0 X-Spam_bar: / X-Spam_report: (0.0 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FORGED_FROMDOMAIN=1, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=1, RCVD_IN_DNSWL_NONE=-0.0001, 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:253174 Archived-At: 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. > 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? BTW, did you read the latest version of it in master? > 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 ? > > 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. > 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'. It's a good quick overview, even if you'll have to guess at the semantics of "current project".