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: master 1e3b0f2: Improve doc strings of project.el Date: Mon, 13 Jul 2020 04:51:33 +0300 Message-ID: <99bb8976-580a-ef8e-6b7d-130c3ca5cb8a@yandex.ru> References: <87bllfqj82.fsf@warpmail.net> <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> <83eepgomts.fsf@gnu.org> <83a704okmg.fsf@gnu.org> <5d59dd9b-0848-691a-615e-c16d2070b92d@yandex.ru> <837dv8oida.fsf@gnu.org> <834kqcoghk.fsf@gnu.org> 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="17180"; 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 Cc: philip@warpmail.net, theo@thornhill.no, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Jul 13 03:52:11 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 1jundb-0004NJ-I4 for ged-emacs-devel@m.gmane-mx.org; Mon, 13 Jul 2020 03:52:11 +0200 Original-Received: from localhost ([::1]:48654 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1junda-0007Yr-KH for ged-emacs-devel@m.gmane-mx.org; Sun, 12 Jul 2020 21:52:10 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:60392) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jund6-00078V-DZ for emacs-devel@gnu.org; Sun, 12 Jul 2020 21:51:40 -0400 Original-Received: from mail-wr1-x433.google.com ([2a00:1450:4864:20::433]:43069) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jund4-0005nR-IJ; Sun, 12 Jul 2020 21:51:40 -0400 Original-Received: by mail-wr1-x433.google.com with SMTP id j4so12979221wrp.10; Sun, 12 Jul 2020 18:51:37 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:subject:to:cc:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=EjJ7/6LotfkR+/E67Xaf2OU09GwIwc2wwqZHJRz7LMA=; b=bzMxgCUO7XXuJY5ccs2MYHewjnzIRUWBCwAMRSBpdcmpyyXcCOWHCUA19ncNCSgowg 0ix8ThMmUV02h4et17YFY10XQyooG5ylXe2J274w1jJ3EN4SrB+Iuh0ZGHeo24g05XQn s5/h+TKaQkU8vt7bBZvyitzxhC63cpdAqFyawyYYfhzF3ZakcTatF59STrVL3KcHVCmY /gZSXEM15AJNtQPJ2gXtWntg3b8OVqhd5evoIFjMgXur1aSjgdU7mGkHEl5wIXbxlK9x CwqtXA6V1BJxG9kfmGNqr8uKZNyUCo21UOsDjMyRn9pV9aP9ws5/qLXhs1xre5OeepkK zYyw== 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:cc:references:from:message-id :date:user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=EjJ7/6LotfkR+/E67Xaf2OU09GwIwc2wwqZHJRz7LMA=; b=o1Ggb/jP1haOQEQh3pu9ohIenb04VSV7zSU0utDnPy7bhwe8tTllw9iEDQ8Vbc5aoF uyLMmB9a8t1iVVEo5Tzugf1N1Di+9JDlAD+ta0avmPqJk2Yil3SIi20vRqHe6+PUu1iY h2ZGTSquXZjF0p2Edj9NzNnm/NF3Y238k7afcwAiQTQbmXbdKmNHJIak1Zr4+6TmGTiA CLtCoWY/SIGfim5pVbpYfmIT5dxkfRJemiZO/DMmm6F2Q7hwEpexs68Mz6mQzL7hzr3I URCjIHixBkS2Zd2czcJuVh2arf/ONAPpVDixguTLXLLxtdR7O1Fx4wHmdVjSwdYhbOop 4vmw== X-Gm-Message-State: AOAM532vbl/lw4eZNB2tovtvIHBseiFXeYc5oY2VWP/SgWH8RDPwQ3bR wbDox/MgRM0c76ssmjhA9iqAzapZ X-Google-Smtp-Source: ABdhPJwf6EM/eiRd5zunXUdY3ZBIx//HYyJFeFTI70YH9iZybi9zMxxoc7A5OsIcjXTE/lsWkQwJ6w== X-Received: by 2002:adf:e88b:: with SMTP id d11mr66118043wrm.378.1594605096087; Sun, 12 Jul 2020 18:51:36 -0700 (PDT) Original-Received: from [192.168.0.3] ([66.205.73.129]) by smtp.googlemail.com with ESMTPSA id c25sm19402749wml.46.2020.07.12.18.51.34 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sun, 12 Jul 2020 18:51:35 -0700 (PDT) In-Reply-To: <834kqcoghk.fsf@gnu.org> Content-Language: en-US Received-SPF: pass client-ip=2a00:1450:4864:20::433; envelope-from=raaahh@gmail.com; helo=mail-wr1-x433.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:252894 Archived-At: On 12.07.2020 19:17, Eli Zaretskii wrote: > Can we approach this from a different angle, please? Can you tell why > you are so opposed to having this small piece of information in the > doc strings? What harm can it do that you consider unacceptable? Let's try this again. This information is private (or "internal") similar to when we designate variables or function private: we don't want people to rely on it because a) that might lead to wrong decisions, b) that might lead to breakage because this information is subject to changing at will. For example, I'm considering turning the whole value into a list (it's currently a shallow cons) and adding the VC backend symbol to the project-try-vc's return value as the second element to save some CPU cycles. Here are things we want third-party code to be able to do: - Consume the public project APIs, which are currently limited to 'project-current' and several generic functions defined for project instance values, to define new commands or supplement existing ones (e.g. to query the current project for its root or its list of files). - Create new project backends. Note that we don't want *everybody* to do that because creating a well-performing backend is a significant amount of work (unless the user has very particular needs and works with small projects). But we want this to be a solid option, and it would be ideal if, say, a handful of backends become popular someday. To create a backend, one needs to choose the format of its instance value (which shouldn't match any of the existing formats), write its project-find-functions element, and define the project-root override that dispatches on its instance value. Preferably, also implement overrides for project-ignores and project-files. Neither of these options requires knowing the exact format of project-try-vc's return value, if only to stay away from it. But the odds of a collision seem very low (and there are ways to reduce them even further). Here are, on the other hand, things that people generally shouldn't do, and yet I have seen them done: - Extract data from the project instance value directly, instead of going through e.g. 'project-root'. For instance, writing (cdr (project-current t)) instead of (project-root (project-current t)). The former is bad code. - Write a new project-find-functions element which returns an instance value that belongs to a built-in backend (usually, the 'transient' one). AFAICT, this is usually done by cargo culting, without understanding of the consequences. Both of these require knowing the exact value formats of project instances used by built-in backends. Thus, documenting them will encourage these usages. I don't want to prohibit the last option outright, but we shouldn't leave any impression that it's legitimate either. And most problems that people try to solve this way (predominantly: customizing project root markers, AFAIK) should be filed as bug reports/feature requests. > I added that piece of information because without it I couldn't wrap > my head around what the code does, in particular when it tries to > determine which projects are equal to which. But it's the wrong direction. I mean, you *can* look at the shape of the instance returned by project-try-vc (which is trivial to do: evaluate the form (project-current t) and look at the echo area), but it doesn't give you any guarantee: after all, we need to make sure project-switch-to-buffer's behavior makes sense for different backends, even ones we didn't write. So documenting that one backend's instance format is not a solution. Instead, it seems we have to document that said value should uniquely identify the returned project and be "stable": not change over time or when fetched from different buffers belonging to the same project. That also means that the value shouldn't contain any caches inside of it. And once we add these requirements, the answer to "which projects are equal" translates to: - The backend is the same, - The instances describe the same project, but the exact fashion depends on the backend. As it would be anyway. > I reckon if this was > difficult for me, there will be others who could benefit from having > that info. This kind of internal information might be better suited for code comments. I'm not sure where you could put this particular bit of information, where it would both be relevant and yet not obvious from the nearby code, though.