GNU bug report logs - #29876
25.3; declaring "internal"/"private" functions

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 29876 in the body.
You can then email your comments to 29876 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: charles <at> aurox.ch (Charles A. Roelli)
To: bug-gnu-emacs <at> gnu.org
Subject: 25.3; declaring "internal"/"private" functions
Date: Thu, 28 Dec 2017 11:30:12 +0100

I often see Lisp functions declared as "internal" or "private" to a
package, either explicitly in comments, or implicitly when their names
contain two consecutive dashes.  We could make the relationship
clearer by adding some 'declare' form like this:

  (declare (internal t) ...)

As a result, we would also be able to document what exactly is meant
by an "internal" or "private" function, the definition of which does
not seem to be written anywhere.  From what I gather, it means that
outside users should not rely on its calling convention and behavior
remaining stable across Emacs versions.


In GNU Emacs 25.3.1 (x86_64-apple-darwin10.8.0, NS appkit-1038.36 Version 10.6.8 (Build 10K549))
 of 2017-09-12 built on gray
Windowing system distributor 'Apple', version 10.3.1038
Configured using:
 'configure --with-modules CFLAGS=-O3'

Configured features:
JPEG RSVG NOTIFY ACL GNUTLS LIBXML2 ZLIB TOOLKIT_SCROLL_BARS NS
MODULES

Message #8 received at 29876 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: charles <at> aurox.ch (Charles A. Roelli)
Cc: 29876 <at> debbugs.gnu.org
Subject: Re: bug#29876: 25.3; declaring "internal"/"private" functions
Date: Sun, 14 Jul 2019 20:01:10 +0200

charles <at> aurox.ch (Charles A. Roelli) writes:

> I often see Lisp functions declared as "internal" or "private" to a
> package, either explicitly in comments, or implicitly when their names
> contain two consecutive dashes.  We could make the relationship
> clearer by adding some 'declare' form like this:
>
>   (declare (internal t) ...)
>
> As a result, we would also be able to document what exactly is meant
> by an "internal" or "private" function, the definition of which does
> not seem to be written anywhere.  From what I gather, it means that
> outside users should not rely on its calling convention and behavior
> remaining stable across Emacs versions.

Hm...  but what would we do with this information in practice?  I don't
think, for instance, issuing a warning when such a function is used in a
different file would be appropriate, because many packages are
multi-file.

The nice thing about the "--" convention is that it's very visible that
the functions are internal, which is something just this declaration
wouldn't do.  So we'd need to do both, and in that case it seems rather
superfluous, because then you could just do whatever you were going to
do based on this information just based on the function having "--" in
its name.

Any other opinions?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #15 received at 29876-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 29876-done <at> debbugs.gnu.org, charles <at> aurox.ch
Subject: Re: bug#29876: 25.3; declaring "internal"/"private" functions
Date: Wed, 14 Aug 2019 10:54:42 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> charles <at> aurox.ch (Charles A. Roelli) writes:
>
>> I often see Lisp functions declared as "internal" or "private" to a
>> package, either explicitly in comments, or implicitly when their names
>> contain two consecutive dashes.  We could make the relationship
>> clearer by adding some 'declare' form like this:
>>
>>   (declare (internal t) ...)
>>
>> As a result, we would also be able to document what exactly is meant
>> by an "internal" or "private" function, the definition of which does
>> not seem to be written anywhere.  From what I gather, it means that
>> outside users should not rely on its calling convention and behavior
>> remaining stable across Emacs versions.
>
> Hm...  but what would we do with this information in practice?  I don't
> think, for instance, issuing a warning when such a function is used in a
> different file would be appropriate, because many packages are
> multi-file.
>
> The nice thing about the "--" convention is that it's very visible that
> the functions are internal, which is something just this declaration
> wouldn't do.  So we'd need to do both, and in that case it seems rather
> superfluous, because then you could just do whatever you were going to
> do based on this information just based on the function having "--" in
> its name.
>
> Any other opinions?

I agree with Lars here, and one month has passed with no one else
chiming in.  I'm therefore closing this.

If anyone disagrees, feel free to reopen.

Thanks,
Stefan Kangas

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.