Re: declare function/macro private

[Stefan Monnier]

>>> Of course there's already the convention of prefix--my-private-function, but
>> What would be the difference between this convention and your proposed 
>> declaration?
> Stefan, you must have missed my followup reply:

No, I'm still wondering what it is you find to be different.

My current guess is that you fear that "--" has currently been used
carelessly and imposing a more "structured" meaning to it after the fact
will hence introduce problems, whereas your declaration would come right
away with an associated "precise" meaning.

If so, I agree to some extent, but:
- As mentioned your declaration would suffer from the difficulty of
  clarifying "internal to what" since sometimes a function is internal
  to a file, sometimes to a multifile package and sometimes to a subset
  of a file.  Of course, that can be solved by adding an extra argument
  to your annotation, but:
- your annotation is placed on those functions that are internal, which
  (as a coder) are those functions which I'd rather not burden with too
  much extra annotations, otherwise I'll just not bother declaring them
  as internal (which is what we had before the "--" convention).
- As long as the effect is just a few font-lock-warning faces here and
  there, I think the problem is harmless enough (and it does point to
  real misfeatures in many cases, so it would help improve the code).

> I think requiring a program to explicitly declare something as internal will
> cause less trouble than adding a kind of compiler heuristic for "--" symbol
> names because there are likely plenty of those where people have used the
> name with the perspective that it's just a hint and doesn't actually do
> anything. e.g. `imenu--index-alist' is supposedly internal but any elisp
> program hooking into Imenu needs to use this variable.

Yes, currently it's a bit of a wild west because the "--" has no effect,
but maybe it's time to impose some order on this, indeed.

> Also I just dislike computer heuristics.

It's not a heuristic.

>>> my thinking here is that a program could declare a function/macro as
>>> private, then the compiler could signal a warning/error if that function
>>> appeared in a library outside the library it was defined and
>>> declared private.
>> We don't have a definition for "library", sadly.
> M-x find library says otherwise. But the definition of a "library" is
> inconsequential. Using "file" might be more helpful.

But "file" is the wrong granularity for many Gnus-internal definitions
(and same applies to all multifile packages).  So what would use for
those if your declaration are only for file-local internal definitions?


        Stefan