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