--- Begin Message ---
|
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
--- End Message ---
--- Begin Message ---
|
Subject: |
Re: bug#29876: 25.3; declaring "internal"/"private" functions |
|
Date: |
Wed, 14 Aug 2019 10:54:42 +0200 |
Lars Ingebrigtsen <address@hidden> writes:
> address@hidden (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
--- End Message ---