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

[Ted Zlatanov <tzz@lifelogs.com>]

On Fri, 11 Mar 2011 13:31:30 +0900 Kenichi Handa <handa@m17n.org> wrote: 

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

KH> This is a little bit different topic, but shouldn't we have
KH> a way to distinguish functions/macros/variables for public
KH> API from those for internal (i.e. only within a specific
KH> package) use only.  For instance, as basic-save-buffer-1 is
KH> just a helper function of basic-save-buffer, there's no need
KH> to list it by C-h f TAB.

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

I think (or autoloaded-p called-interactively-p) functions are
implicitly intended for public consumption so maybe that's the criteria
you're looking for (I'm inventing some of these predicate names).

But maybe it also makes sense to add filtering by `autoloaded-p' and
`called-interactively-p' (which is currently available with M-x TAB) and
`has-docstring-p' to `C-h f' somehow, either by making parallel commands
or by adding filtering inside it.  So then public-API-p can be part of
that system, if it's different from (or autoloaded-p called-interactively-p).

Ted