From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: "Paul W. Rankin" via "Emacs development discussions." Newsgroups: gmane.emacs.devel Subject: Re: declare function/macro private Date: Mon, 7 Jun 2021 10:59:16 +1000 Message-ID: <7D467006-748F-4316-939E-C82D62D80221@bydasein.com> References: <0278C47F-42CE-45C4-B789-83C57DF1A191@bydasein.com> Reply-To: "Paul W. Rankin" Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.100.0.2.22\)) Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="4778"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Stefan Monnier Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Jun 07 03:17:43 2021 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 1lq3td-0000zv-Lp for ged-emacs-devel@m.gmane-mx.org; Mon, 07 Jun 2021 03:17:41 +0200 Original-Received: from localhost ([::1]:57932 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lq3tc-0000PW-LX for ged-emacs-devel@m.gmane-mx.org; Sun, 06 Jun 2021 21:17:40 -0400 Original-Received: from [2001:470:142:3::10] (port=39890 helo=eggs.gnu.org) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lq3eE-00043w-Td for emacs-devel@gnu.org; Sun, 06 Jun 2021 21:04:29 -0400 Original-Received: from sendmail.purelymail.com ([34.202.193.197]:47264) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lq3dE-00067k-2M for emacs-devel@gnu.org; Sun, 06 Jun 2021 21:01:31 -0400 DKIM-Signature: a=rsa-sha256; b=KlLpW2pG6V36cmQlXeqHoGsfsjm2z7qJVNswlBnxy9JNa6332yWwQwVj36Pow7LyDxmFMk/MT9noNH3e1LCvbnKRmhMAco/zrWa4o9bszBSkRXoa8zntQQ+xspGSikXKa8FwKc8ya8paOSYWq1tQRl+Wg9UCG0UqvU/jPhxIZW5F7XhDfG0Hf43yKp6ChOFvvfySmtFtyHb9cR6XjGdJGkUAL8UJRmgZ/G+vjXRV7O9xgSwOvMS5yn0XJL8dUWiuM7Am4kCa7KmTcrJx5qNPO0VprQY3CSQ4WBhKpOm5SQOTIiQ7/OHff/UKAzGGbb3LVSiPanqjrkd6Glo6TD7Ozw==; s=purelymail3; d=bydasein.com; v=1; bh=ClSLnI5/baxNCMzJ9gGXzLLeXM2MutTH9tygQt1ljUc=; h=Received:From:To; DKIM-Signature: a=rsa-sha256; b=D0JJ2R4DyYO8kGpV+gAbEKa9sPX4GZRlUWhMnFn0Zw0XCq7DglU9wXv+fpqorEvzVJiPB+ppl/PQjsoWq/rx85KMtxvSjQV/UybaoNBfJQlum7cfDVufM0WToA6SldNsxGPRLeeEOoq3UChQi/tsznnNcqyDpR9K2s6B8PjFYJ1dD2/l9C1Z9WocJWQZ1XzVg+aD2Icqqmd8NzWJEF/QeRUokmKmWEQfzid8HZRbF/rkF1U3tdflycvcixLuFs83dwzHjL58qUe2UYAZs1Z7SAY3+MSyyHLhZJ2WBJfD/t61XPoAkjz9mEeq6DREirk5ky+gTph4liDEWqGKC2cmeA==; s=purelymail3; d=purelymail.com; v=1; bh=ClSLnI5/baxNCMzJ9gGXzLLeXM2MutTH9tygQt1ljUc=; h=Feedback-ID:Received:From:To; Feedback-ID: 791:353:null:purelymail X-Pm-Original-To: emacs-devel@gnu.org Original-Received: by ip-172-30-0-164.ec2.internal (JAMES SMTP Server ) with ESMTPA ID 1169586393; Mon, 07 Jun 2021 00:59:23 +0000 (UTC) In-Reply-To: X-Mailer: Apple Mail (2.3654.100.0.2.22) Received-SPF: pass client-ip=34.202.193.197; envelope-from=pwr@bydasein.com; helo=sendmail.purelymail.com X-Spam_score_int: -16 X-Spam_score: -1.7 X-Spam_bar: - X-Spam_report: (-1.7 / 5.0 requ) BAYES_00=-1.9, DKIM_INVALID=0.1, DKIM_SIGNED=0.1, T_SPF_HELO_TEMPERROR=0.01, T_SPF_TEMPERROR=0.01 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:270508 Archived-At: > On 7 Jun 2021, at 4:05 am, Stefan Monnier = wrote: >=20 >> Of course there's already the convention of = prefix--my-private-function, but >=20 > What would be the difference between this convention and your proposed = declaration? Stefan, you must have missed my followup reply: ..that would be great if a function declared as internal appears outside = of its program then it gets highlighted in font-lock-warning-face. Then = the curious programmer calls `C-h f' on it and the help buffer could = show e.g. This function is internal to and should not be used in other lisp programs. Use instead. The "--" convention is fine and I wouldn't suggest to change/replace = this; it's clear to people what it means once they've learnt what the = convention means. I think requiring a program to explicitly declare something as internal = will cause less trouble than adding a kind of compiler heuristic for = "--" symbol names because there are likely plenty of those where people = have used the name with the perspective that it's just a hint and = doesn't actually do anything. e.g. `imenu--index-alist' is supposedly = internal but any elisp program hooking into Imenu needs to use this = variable. Also I just dislike computer heuristics. I'll revise the initial suggestion from `private' to `internal' since = that's more the Emacs lexicon, i.e. (declare (internal t)) (declare (internal "use `other-function' instead.")) >> my thinking here is that a program could declare a function/macro as >> private, then the compiler could signal a warning/error if that = function >> appeared in a library outside the library it was defined and >> declared private. >=20 > We don't have a definition for "library", sadly. M-x find library says otherwise. But the definition of a "library" is = inconsequential. Using "file" might be more helpful. > I think the "--" convention actually includes an extra information > compared to yours which could be useful here: we could warn for uses = of > "foo--" if and only if the use appears in something whose name doesn't > start with "foo-". >=20 > IOW, use the string before the "--" as the definition of the "library" > (so that would support cases where a library is spread over several > files, as well as the case where a single file contains "internal > libraries"). >=20 > Of course, if we enable such a warning now, we'll get a fairly large > number of warnings, I think ;-) >=20 > Another advantage of the "--" convention is that you don't need to = load > the definition of that function in order to discover that it's = private. I'm not suggesting to do away with using "--" as a handy visual marker. = I use that too. I would caution that trying to introduce a heuristic approach to = interpret human intent from just "--" in a symbol name is the path to = ruin. As for the case of "libraries" over separate files, again it's probably = best to use the word "file" instead of "library" to define the limits of = the suggestion; consider declare-function as corollary: Tell the byte-compiler that function FN is defined, in FILE. And `(declare (internal t))' would be: Tell the byte-compile that this function is internal to this file.