Re: declare function/macro private

[Arthur Miller <arthur.miller@live.com>]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

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

I think one of problems with '--' is that is *relatively* new
convention. Lot's of old code in Emacs sources does not follow it, and
lot's of 3rd party packages does not follow it. Some older 3rd party
packages use different conventions like 'prefix/function-name' or
'prefix:function-name', where prefix is package name. As Ingebritsen
wrote in some other mail yesterday you could have Emacs highlight
syntax, but then there should be some way to tell Emacs what prefix is.

What OP propose is to have programmatic control over what is
"public/private", but in my opinion, as he suggestes, it would be quite
tedious to type for each and every "private" function an explicit
declaration as he proposes. People would probably not do it, just like
they don't care to write proper javadocs, doxygen docs and other
"proper" things that require explicit work.

But if Emacs can auto detect prefixes as "private", than it is
completely different game.

Also there should be some way to distinguish between code in same
package which shouldn't produce warnings and client code that uses
library where warnings should be emited if a "private" function is used.