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