bug#29876: 25.3; declaring "internal"/"private" functions

bug#29876: 25.3; declaring "internal"/"private" functions

[Charles A. Roelli]

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

bug#29876: 25.3; declaring "internal"/"private" functions

[Lars Ingebrigtsen]

charles@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

bug#29876: 25.3; declaring "internal"/"private" functions

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> charles@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