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: Tue, 21 Jul 2020 04:09:18 +0300 Message-ID: <69716ecb-8984-23e0-8b44-322ea3582384@yandex.ru> 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> <6edffb7d-7708-534f-93ad-bf9180f5e0ed@yandex.ru> <835zamjsvk.fsf@gnu.org> <831rlajock.fsf@gnu.org> <1fcdc463-b3ab-2d32-31d7-904783ae0d81@yandex.ru> <83y2nii6sk.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="12264"; 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: eliz@gnu.org, npostavs@gmail.com, emacs-devel@gnu.org To: rms@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue Jul 21 03:09:57 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 1jxgn6-00034X-R7 for ged-emacs-devel@m.gmane-mx.org; Tue, 21 Jul 2020 03:09:56 +0200 Original-Received: from localhost ([::1]:39248 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jxgn5-0005f8-R8 for ged-emacs-devel@m.gmane-mx.org; Mon, 20 Jul 2020 21:09:55 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:48158) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jxgmc-0005Fc-6M for emacs-devel@gnu.org; Mon, 20 Jul 2020 21:09:26 -0400 Original-Received: from mail-ej1-x631.google.com ([2a00:1450:4864:20::631]:35046) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jxgma-0001bt-AP; Mon, 20 Jul 2020 21:09:25 -0400 Original-Received: by mail-ej1-x631.google.com with SMTP id rk21so19975271ejb.2; Mon, 20 Jul 2020 18:09:23 -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=VLyeJ3XFWeUsQTJVzfv8IuYiVDGaLh0o9zQqx1g/IlY=; b=XaJg11h8LUlX4fb0ynOILa7rrabdQ0TnQLS0wuC/zo0uwKktkIYiPuUVyHbD2nzs5I xI7M+eGM3FYP3zBzbjbPhddi7S8Yr4Ib6/6lC6xlDGeGAjb2OcxAEe365d7mtod9EXR4 HyqmnEK4hVeI+BjSJRqq7EC15T2Dqj2nDcrlallJoFuqcsil41c6eKsFxmzmxQq4YHKd QE48d5KAUcNF/tCRGSOyafnBMqharsFqFbUk6n1EXyBOqJDcn8DAIXWOzR5AnLYKgUcy D1ETfXzJizaD/RVrLACCl+/X9NKRmo79vJLPx48LnzRVBlo3ZzXiXMrQVUjLByJZkP2F PNlA== 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=VLyeJ3XFWeUsQTJVzfv8IuYiVDGaLh0o9zQqx1g/IlY=; b=Qe58hDhdOVSifR2geRVg2lza6mO8/2YApEvIPYgW6+clhs5bVN0RYAyn9fA8qo/9nG O/P16RBEo1MBQBCuCUXIFbVUyAbmstoa88ibJX6o4uHk0hEHSlEPORxZSHvbO2ONnUQC OBPpp0xWrla3z2/0ErDTMdJuSm5TUG6cpiuzfG7NIkK5tNxSA1Z7HrRk6Gb/y7leQpXA HagPAPZJJNXfFK0Ilbfn0uA3qubj4i/mHTGWt08vucVHUMPLU9ZTObxcar93E5KhRTRK j0dDqbRkAYz9tBcODS92pRVBvT7bsj2K1Q3nCJWvLRwsX47z/FZjYrFv24Y+WNRBfGt4 9qZA== X-Gm-Message-State: AOAM530lz0Kj/M4cQmIv1O+1tZ9ImVTQg4RsWfy1js64xbO1pxiNOUXJ XmHltQyScuYiEZJqZ+eggyZHzMeD X-Google-Smtp-Source: ABdhPJyOEdwHZm/pA4FLWbWGYDj1HJtqYowBosR3Vv9v0HKf80h7jTz/FRK87sAHvih+p6T87/hZQg== X-Received: by 2002:a17:906:a0c8:: with SMTP id bh8mr24201488ejb.190.1595293761165; Mon, 20 Jul 2020 18:09:21 -0700 (PDT) Original-Received: from [192.168.0.3] ([66.205.73.129]) by smtp.googlemail.com with ESMTPSA id ce15sm15771949ejc.86.2020.07.20.18.09.19 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Mon, 20 Jul 2020 18:09:20 -0700 (PDT) In-Reply-To: Content-Language: en-US Received-SPF: pass client-ip=2a00:1450:4864:20::631; envelope-from=raaahh@gmail.com; helo=mail-ej1-x631.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:253128 Archived-At: On 20.07.2020 05:44, Richard Stallman wrote: > [[[ To any NSA and FBI agents reading my email: please consider ]]] > [[[ whether defending the US Constitution against all enemies, ]]] > [[[ foreign or domestic, requires you to follow Snowden's example. ]]] > > > Consider the docstring of said constructor function. What should it say > > its return value is? > > One natural possibility: > > Return an empty project object. You need to store values in it with ... > > Another: > > Return a project object with name MAME and containing files FILES. > > I am guessing here. I don't know what these projects do. > I don't know what data a project object should have. Okay, see, neither option is going to work. We have a "factory" function (called 'project-current') which delegates project instance creation to a hook. Which is what makes it extensible. The only argument is DIRECTORY, meaning the current directory. The functions in the hook get called in turn, and the first one that returns non-nil is going to be used. Its return value must be a "project instance" which satisfies a certain protocol defined by several cl-generic methods (think "interface" in Java, or "typeclass" in Haskell, or "protocol" in Clojure, or multimethods elsewhere). One method is mandatory to be defined for all project implementations, the rest have default implementations. Thanks to the cl-generic infrastructure, the datatype representing the current project can be almost anything, and the structure of the fields inside can be arbitrary. This is sorted out by each individual backend which knows how to access fields inside "project instances" belonging to it, and which implements the aforementioned protocol for that instance type. The two built-in backends use very simple structures (right now: conses like (TYPE-TAG . PROJECT-ROOT)), which is very obvious from their implementations. The core of the dispute is whether project-current's docstring should document the return value in detail (giving an example of built-in project instances's structure). Eli is insisting on it because (AFAICT) that suits his thought process and he thinks that will help users/clients to make sense of how things work. I am adamantly against this because it's against the design (clients should program against the public interface, not against the implementation), and is likely to encourage incorrect programs. Of course, we can add this information elsewhere, e.g. in the comments of the "backend" functions (which are the elements of the hook I mentioned above). I haven't done so because, well, the implementations are fairly transparent and the structures are trivial. But I wouldn't object against somebody doing that. > It is important to document the meaning of each slot -- that may not > be obvious. Which values are valid? The space of possible structures of valid project instances is theoretically infinite.