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

["Drew Adams" <drew.adams@oracle.com>]

> 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 have no problem with that in principle.  From my point of view, "internal"
here would be something definable (e.g. declarable) by the coder.

IOW, it has no intrinsic meaning; it can only be defined by someone, in some
context, with some purpose.  Its only value is relative to those things.

It expresses the coder's intention that most users will probably not want or
need to use the stuff designated "internal" most of the time.  Nothing more than
that.

> 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 sure disagree here.  "No need" isn't something the coder can decide.  "You
probably aren't very interested in this" is different from "you don't need
this".

Personally, I want `C-h f' to include all functions as candidates.  This is
`describe-function', not `describe-user-function' or some such.

I have no problem with someone adding a new command to do what you describe.  I
would prefer that it not be bound to `C-h f', but that's another matter (and I
certainly wouldn't go to the barricades about it).

Or a prefix arg might be acceptable for distinguishing the two.  Then we would
be arguing only over the default behavior (behavior with no prefix arg).

But my personal preference, used in my own version of `C-h f', is for a prefix
arg to mean use only _commands_ as completion candidates.  Perhaps a distinction
via different prefix-arg values would be appropriate: all functions, only
commands, only "external" functions.

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

Again, "internal" means nothing (especially) for a language like Lisp
(especially a Lisp that has no packages/modules), other than as an expression of
a coder's intention.  That's not nothing, of course.  And there's nothing wrong
with expressing such an intention - it can be helpful.  But "internal" can (and
should) never be more than that: expression of intended use by most users in
most situations.

People are users at different levels at different times or in different
contexts.  Something is language in one context and metalanguage in another
context.  Same with internal and external.  One person's or one context's
internal is another person's or another context's external.

That does not mean that such terms are meaningless or useless; it just means
that they are far from absolute.  Sooner or later someone (and not only the
maintainer) will want to use "internal" functions for something - possibly
something "external" or unintended originally.  Code manipulation (by code) is
just one example.