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, 20 Jul 2020 00:59:07 +0300 Message-ID: <1fcd8470-4763-552c-83a6-511f514701d5@yandex.ru> References: <5d59dd9b-0848-691a-615e-c16d2070b92d@yandex.ru> <837dv8oida.fsf@gnu.org> <834kqcoghk.fsf@gnu.org> <99bb8976-580a-ef8e-6b7d-130c3ca5cb8a@yandex.ru> <83y2nom3hy.fsf@gnu.org> <20200713075842.GA4332@tuxteam.de> <21b47cbb-d1aa-d875-2944-deebb7583961@yandex.ru> <20200717152702.GA18658@tuxteam.de> <922bca06-3425-6fa3-b184-89942c75e91d@yandex.ru> <20200718090546.GC30436@tuxteam.de> <3ae3a7c3-f8c4-a4de-d8bf-d4d62f8f4c44@yandex.ru> 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="16150"; 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: tomas@tuxteam.de, emacs-devel@gnu.org To: rms@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Jul 19 23:59:58 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 1jxHLh-000453-8i for ged-emacs-devel@m.gmane-mx.org; Sun, 19 Jul 2020 23:59:57 +0200 Original-Received: from localhost ([::1]:56516 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jxHLg-0000jM-8v for ged-emacs-devel@m.gmane-mx.org; Sun, 19 Jul 2020 17:59:56 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:60346) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jxHKz-0000Ja-Jq for emacs-devel@gnu.org; Sun, 19 Jul 2020 17:59:13 -0400 Original-Received: from mail-ed1-x536.google.com ([2a00:1450:4864:20::536]:34465) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jxHKx-0007Ak-PV; Sun, 19 Jul 2020 17:59:13 -0400 Original-Received: by mail-ed1-x536.google.com with SMTP id a8so11457450edy.1; Sun, 19 Jul 2020 14:59:10 -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=RiNGeNYfpKCvILUGJUn3snDsX64Tl6ylLLBQ/lsq40Y=; b=JK7plWmZ9OMqekN1ExFpRHIBwuYSFeMnoNxt+TvBkXkxb/M+lY367ldZUyhBkViYAN SGCuxjnvSgFF/TE0Z6i9jmXaLriwknk9y2oD8S5cOj0VikXW1oa3ma0+h7mywgg2UbhS GQczQWu/E6V26VS3OtRD5ECGODQSlLLS9XmHWUsGz23ADDkUmVg9btMz//1xTns2+cL5 I8yr9LmzHrT5pfwBCPu4q8snEZUDKHvvKMa7/eQFkLrqxWv/efnIcycRGjCNZd33+ovX AG1ufGTeSk7PqJUfDTKvWAFU6iEz6TWncZYYIBkuOYWTaZ2xx5yCsfQIxWNjRfudv1XY Bdgw== 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=RiNGeNYfpKCvILUGJUn3snDsX64Tl6ylLLBQ/lsq40Y=; b=rnpk7c9mYpRB1Z6TiA1COWhYsANs+Uq7xvCGBvv37RF465AgA1Qs8HqeWrujF3agAx ubkNM+J9y9vp8LSx82Xmfxhguez9g23XWzGCGCFxER/OyvfTpvIjCQFwm5CANQpuWGIK ytAqBGNZPhzJ5TgQfW8V3IvBg8hboocTayBpNKnS3ym57cyEsDee4oDJLiplQS1FWtNY Y74m0Ko9CDZahtgEYny6T1mEEpTn9GV+7HKogAMRdw+uXocjD0jNzsHDuCQbfzlZJD0S z/kNwEFNTCKuAV6AU6Tbl6EOLWqqdEOcz5YNlfROfKcB/5WZMVcILH80mNrnlHxAxc/N ezNA== X-Gm-Message-State: AOAM533L6zlfUhGPqRWRF7zRy8xvsUlLAttdaN7ZZ7PiWhWNeItOqcve lHDvQ8c1kx9BLk6SZTOupY/SiGjZ X-Google-Smtp-Source: ABdhPJwjEIuFU334aBupUnGG2rHDgs3bl2F4A2hyU/UDrS22RdXs7r5JifZjX5Tw3S3v9o+NSHT8sg== X-Received: by 2002:a50:a125:: with SMTP id 34mr6073473edj.306.1595195949188; Sun, 19 Jul 2020 14:59:09 -0700 (PDT) Original-Received: from [192.168.0.3] ([66.205.73.129]) by smtp.googlemail.com with ESMTPSA id h15sm13199579eja.44.2020.07.19.14.59.07 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sun, 19 Jul 2020 14:59:08 -0700 (PDT) In-Reply-To: Content-Language: en-US Received-SPF: pass client-ip=2a00:1450:4864:20::536; envelope-from=raaahh@gmail.com; helo=mail-ed1-x536.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:253114 Archived-At: On 19.07.2020 05:27, 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. ]]] > > A Unix file descriptor is a datatype which is semantically opaque and > has a representation which is literally opaque. There is nothing > inside it that a user program can make sense of. Once the developer > of the user program knows this much, there is nothing more to say > about it. But there are reasons behind this state of affairs. It's a man-made design, not a force of nature. My point is, having semantically opaque datatypes can be good for us, in certain applications. > The package data structure is a very different case. It is made up of > Lisp data structures which any Lisp program, and any Emacs user, could > look inside. > > I gather that package.el provides a complete API of functions to do > everything anyone would wish, with this data structure. If so, people > and programs invoking package.el don't need to know how that data > structure is made up. There is no need to describe it in doc strings. This discussion is about project.el, not package.el. But I think we agree on the general point: as long as people and programs provide an adequate API (which is our goal anyway), we don't need to describe in detail how its data structures (plural, in this case) are made up. > But people working on package.el in the future, and people trying to > understand it, do need to know its structure. So it should have > comments which explain. (I expect Linux has comments describing the > meaning of file descriptor data structures.) I have nothing against comments, but in this case the data structures are pretty trivial and obvious from the functions that create them. So I don't immediately see anything in there that would need clarification in comments, but would not stop people from doing so. > We shouldn't wait to document that data structure, because any one of > us (and that includes you) might, at any moment, suddenly be unable to > continue working on Emacs. With luck, you won't have to stop this > year -- but it will surely happen some day. Indeed.