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