From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Arthur Miller Newsgroups: gmane.emacs.devel Subject: Re: declare function/macro private Date: Mon, 07 Jun 2021 20:24:33 +0200 Message-ID: References: <0278C47F-42CE-45C4-B789-83C57DF1A191@bydasein.com> <7D467006-748F-4316-939E-C82D62D80221@bydasein.com> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="12672"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) Cc: "Paul W. Rankin" , 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 20:26:14 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 1lqJx0-00038p-O6 for ged-emacs-devel@m.gmane-mx.org; Mon, 07 Jun 2021 20:26:14 +0200 Original-Received: from localhost ([::1]:46866 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lqJwz-0006WH-Pq for ged-emacs-devel@m.gmane-mx.org; Mon, 07 Jun 2021 14:26:13 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:48266) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lqJvW-0005fh-QB for emacs-devel@gnu.org; Mon, 07 Jun 2021 14:24:43 -0400 Original-Received: from mail-oln040092065107.outbound.protection.outlook.com ([40.92.65.107]:54913 helo=EUR01-HE1-obe.outbound.protection.outlook.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lqJvT-0004us-AI for emacs-devel@gnu.org; Mon, 07 Jun 2021 14:24:42 -0400 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=XTic5IYWF9jIX/WEyxw05LCt9UFVpgHTfagz6xK349r9UBMOZZ5rVj/jVeCPUMii0s3BtrENeKwkwM8q2BqBsdAYDEpcBVru3Jw3SnCebm81uE+nVUC1Pl2uemcin0iEUqMlWfVR16+a0KOsZvXCIka5dLwrJDUvyIkm3jaCaRSNZAWjRW7x2RQlV4hW3vqrMFgC8HDwvVCI8/PRgC5SmrRAYnUbRDOGExX6Hjov4Il+4iUn6pUdc7j3muP7GnFbfb4FX0JuVz2uFPs4kI/WekSMHPb3OMlFrjf48syWUxHZuTS9TmCeA71pQPkeapOZbg4ngKwszOPnvTVEugHrvA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=jPJ7BDzzXLbUUnxSWsCE2pu+BzH1+Ecb3Q7bJcKfG3k=; b=b0S6hFTFB9Dy0Y8DXwIKFUyDiRpjkWhTTg5LzW/zAW1lXeqylLV0QRRjQP87TfQxkjyxfnXE4lkbiALCepUpUbyAclxKuB3qsYuw9fUaVLAAwHU1RdDENTpQBYjGpwyCaWRRDl67F+r2DluGKapvr6KsYr1uYswgx+3eye9fo/+xU1zX7+Q1Sr+PzHh9q1MHtjvOeS29W9VO/1R1aTJ4urgRM21jg7BNJUBbwG6p5YoZLwL4CHB8hH1i4fQhoZLNO1OegTGspBCUVnthQW/F/8MjCXa8A+3O9Z5GAasA45M1XR1rVycDfw+tQ8203zz/2hrJR0NZRDvXQvwVhAouIg== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=none; dmarc=none; dkim=none; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=live.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=jPJ7BDzzXLbUUnxSWsCE2pu+BzH1+Ecb3Q7bJcKfG3k=; b=VTBh7fKvDE9Szn+h5xdWrwrbpiduC/om6EHf0XetFQvlfgCZtqfkd3C2NtZtUrilUNAVhauUNStvulZH5dpN/MgubgtaPLtf3mU24X4aluTIyImHsQE7zbkASVyUuB+W0Fu+f7mnDaRrhmIB4XRjbffgLazfBtJnTkbnVC0WifTxogh4sasjY8UEolaHInDugioBvxs60ElwWA69uUYplCfFOAhAyPdrZPHSN5b1ahmVFgH9x2zqqHTjx0zgYyBTURNx+p8S7xgO08TLfFXFhlD4HBNAouNQ40tPbAlYH/mR+SfUauBnNjO/usrRX9jyevtu8QRdoR4nTJCzi2gq5A== Original-Received: from HE1EUR01FT063.eop-EUR01.prod.protection.outlook.com (2a01:111:e400:7e18::51) by HE1EUR01HT169.eop-EUR01.prod.protection.outlook.com (2a01:111:e400:7e18::411) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4195.18; Mon, 7 Jun 2021 18:24:34 +0000 Original-Received: from AM9PR09MB4977.eurprd09.prod.outlook.com (2a01:111:e400:7e18::47) by HE1EUR01FT063.mail.protection.outlook.com (2a01:111:e400:7e18::307) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4195.18 via Frontend Transport; Mon, 7 Jun 2021 18:24:34 +0000 X-IncomingTopHeaderMarker: OriginalChecksum:06794F3D3498D4BCDF1A29A3361584E5E48E8DEBA95A60D691689DA0D07BAF82; UpperCasedChecksum:545CB5613116AEB9F1DFB3B4F5DEE3B09B4B5A9E908706455886C0AE3929F51C; SizeAsReceived:7596; Count:46 Original-Received: from AM9PR09MB4977.eurprd09.prod.outlook.com ([fe80::d1c1:2a0d:3b2b:4591]) by AM9PR09MB4977.eurprd09.prod.outlook.com ([fe80::d1c1:2a0d:3b2b:4591%7]) with mapi id 15.20.4195.030; Mon, 7 Jun 2021 18:24:34 +0000 In-Reply-To: (Stefan Monnier's message of "Sun, 06 Jun 2021 22:54:41 -0400") X-TMN: [BEnH8ktBUwf6G6yyED2oSuLPm+vPvjSb] X-ClientProxiedBy: AM5PR0701CA0017.eurprd07.prod.outlook.com (2603:10a6:203:51::27) To AM9PR09MB4977.eurprd09.prod.outlook.com (2603:10a6:20b:304::20) X-Microsoft-Original-Message-ID: <87sg1tjzxa.fsf@live.com> X-MS-Exchange-MessageSentRepresentingType: 1 Original-Received: from pascal.homepc (81.232.177.30) by AM5PR0701CA0017.eurprd07.prod.outlook.com (2603:10a6:203:51::27) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4219.9 via Frontend Transport; Mon, 7 Jun 2021 18:24:33 +0000 X-MS-PublicTrafficType: Email X-IncomingHeaderCount: 46 X-EOPAttributedMessage: 0 X-MS-Office365-Filtering-Correlation-Id: a1c1e611-8841-4526-ac63-08d929e17fe0 X-MS-TrafficTypeDiagnostic: HE1EUR01HT169: X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: 2fZp6kI15OMnv33c6cPN+Hjq1K+vofjXZ6EZFfnvEWVzzeWPRNanaNxZ3Q11rNN01Bw22u626/HOSetemmLSdj/rcEIGvINXVrK5RD8mwRkmJdp6s2VMaxSV3JdZVTJFPqKVMDJXcHDuy1MJK1YLOfCSA7AbV5fxlqNBxMPsmxBq+CtgMtytU6mnUGRBI7h5AcRXc4vUrU/qyswM8zGDX8u/cYKRsK2HwDR9zhNCQtGnsvI/vCGUsjdJtZw4c1cA/Me6xTFK+JsUeC27r0I05HsQV5kKuoZHoT33zj3nGSDJ4WT6I5pZXCI/WDbcV1SIKnxMZJvd/ZzJ0lEIThVgXUkoMmekXoZYUYcn2Ra0rm+iLGjh5OEJIcFKPAMf2JKScLVx1MqMVlqaEXfu6AEwTA== X-MS-Exchange-AntiSpam-MessageData: cRyDXkquUJV3q0TfNHds4O/3O0a7gyTHQ6CJMZSE3+XNFATfPCjtolUy3TGBXZe6PiU7b/UC7GI46WGv5gROMF+T2oaJ/gW8EbiMZlK85r6OnPHaNBwq3TFp4wYXrYIpsViLAceKBKouH4E1mGuwmw== X-OriginatorOrg: live.com X-MS-Exchange-CrossTenant-Network-Message-Id: a1c1e611-8841-4526-ac63-08d929e17fe0 X-MS-Exchange-CrossTenant-OriginalArrivalTime: 07 Jun 2021 18:24:34.6406 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 84df9e7f-e9f6-40af-b435-aaaaaaaaaaaa X-MS-Exchange-CrossTenant-AuthSource: HE1EUR01FT063.eop-EUR01.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: Internet X-MS-Exchange-CrossTenant-RMS-PersistedConsumerOrg: 00000000-0000-0000-0000-000000000000 X-MS-Exchange-Transport-CrossTenantHeadersStamped: HE1EUR01HT169 Received-SPF: pass client-ip=40.92.65.107; envelope-from=arthur.miller@live.com; helo=EUR01-HE1-obe.outbound.protection.outlook.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, MSGID_FROM_MTA_HEADER=0.001, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham 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:270533 Archived-At: Stefan Monnier writes: >>>> Of course there's already the convention of prefix--my-private-function, but >>> What would be the difference between this convention and your proposed declaration? >> Stefan, you must have missed my followup reply: > > No, I'm still wondering what it is you find to be different. > > My current guess is that you fear that "--" has currently been used > carelessly and imposing a more "structured" meaning to it after the fact > will hence introduce problems, whereas your declaration would come right > away with an associated "precise" meaning. > > If so, I agree to some extent, but: > - As mentioned your declaration would suffer from the difficulty of > clarifying "internal to what" since sometimes a function is internal > to a file, sometimes to a multifile package and sometimes to a subset > of a file. Of course, that can be solved by adding an extra argument > to your annotation, but: > - your annotation is placed on those functions that are internal, which > (as a coder) are those functions which I'd rather not burden with too > much extra annotations, otherwise I'll just not bother declaring them > as internal (which is what we had before the "--" convention). > - As long as the effect is just a few font-lock-warning faces here and > there, I think the problem is harmless enough (and it does point to > real misfeatures in many cases, so it would help improve the code). > >> 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. > > Yes, currently it's a bit of a wild west because the "--" has no effect, > but maybe it's time to impose some order on this, indeed. > >> Also I just dislike computer heuristics. > > It's not a heuristic. > >>>> 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. >>> 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. > > But "file" is the wrong granularity for many Gnus-internal definitions > (and same applies to all multifile packages). So what would use for > those if your declaration are only for file-local internal definitions? > > I think one of problems with '--' is that is *relatively* new convention. Lot's of old code in Emacs sources does not follow it, and lot's of 3rd party packages does not follow it. Some older 3rd party packages use different conventions like 'prefix/function-name' or 'prefix:function-name', where prefix is package name. As Ingebritsen wrote in some other mail yesterday you could have Emacs highlight syntax, but then there should be some way to tell Emacs what prefix is. What OP propose is to have programmatic control over what is "public/private", but in my opinion, as he suggestes, it would be quite tedious to type for each and every "private" function an explicit declaration as he proposes. People would probably not do it, just like they don't care to write proper javadocs, doxygen docs and other "proper" things that require explicit work. But if Emacs can auto detect prefixes as "private", than it is completely different game. Also there should be some way to distinguish between code in same package which shouldn't produce warnings and client code that uses library where warnings should be emited if a "private" function is used.