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

[Kenichi Handa <handa@m17n.org>]

In article <jwv7hc6e7dg.fsf-monnier+emacs@gnu.org>, Stefan Monnier <monnier@iro.umontreal.ca> writes:

> > Yes, it is a bit silly complete keywords, which are not variables by
> > definition.  I'm going to install this trivial fix.

> Sounds good.  FWIW, here's a patch I have pending for the lexbind branch
> (where special-variable-p is t only for vars that have been defvar'd
> or defconst'd).

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.  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.

In addition, and this is more important, such a
distinguishment makes it easier to maintain a package.  For
instance, when I improve the MIME handling of rmailmm.el,
the most difficult thing was to keep backward compatibility
of existing functions.  It seems that most of them are
intended for internal use only.  If that is clear, I could
have renamed or changed the behaviour of some of them.

---
Kenichi Handa
handa@m17n.org