Re: public APIs and private ones (Re: `C-h v' may offer too many symbols)

[Stefan Monnier]

> This is a little bit different topic, but shouldn't we have
> a way to distinguish functions/macros/variables for public
> API from those for internal (i.e. only within a specific
> package) use only.

I try to follow the convention that I use "<package>--" for
functions/macros/variables internal to <package>.  It's just
a convention and it's currently very little used, but I encourage people
to use it more systematically.

We also use the "internal-" prefix for things that are "internal to
Emacs core" (typically functions exported from C meant only for use in
subr.el, tho I also used it in lexbind for operations that only appear
in some intermediate form of the code manipulated by the compiler).

> For instance, as basic-save-buffer-1 is just a helper function of
> basic-save-buffer, there's no need to list it by C-h f TAB.

I'm not completely sure if it would be a good idea: I also use C-h f to
find such internal functions.

> In addition, and this is more important, such a distinguishment makes
> it easier to maintain a package.

Fully agreed.  It also makes it easier for users of the package to
figure out what are the intended entry points.


        Stefan