Re: declare function/macro private

[Paul W. Rankin]

> On Sun, 06 Jun 2021 22:54:41 -0400, Stefan Monnier wrote:
>
> 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.

I was *so sure* I had made this clear having said it four times, but 
okay: I do not wish to impose or change anything.

Now, I *know* that someone on emacs-devel will read that and decide it 
means "he wants to impose or change something" so again, for that 
reader: please put down your pitchfork, re-read the initial email, 
understand that it does not suggest imposing or changing anything.

What I am suggesting is that if a programmer wishes to make it 
abundantly and extraordinarily clear that a function/macro is internal 
and should never be used outside of this program, they would have this 
extra declaration which they could explicitly set that would provide a 
simple and discoverable warning to other elisp programmers.

An optional addition. That's it. No one forces anyone to use it, just 
like we have the interactive-only declaration and no one's house burnt 
down.

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

I think internal to the file is easiest but if there's some easy way to 
make it "internal to the package/library" then cool. But as you've 
already said, does Elisp have a definition of what is and isn't part of 
a package/library? Not really. It does have plenty of things that work 
file-local though.

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

For you nothing would change.

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

Cool.

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

I am not suggesting imposing anything. Trying to retroactively impose 
some definitive meaning upon people's use of "--" is, as I said, the 
path to ruin.

Others do not necessarily know what I know, i.e. while I may know that 
"--" is a convention that means "internal" in Elisp, other people may 
not (or likely do not). I suspect many programmers use it just because 
they've seen it used in other packages. And given that Elisp does not 
have any explicit definition of what is "internal" it would make little 
sense to impose one now and say "oh well that's what we meant all 
along".

So could someone prove how clever they are by making some sort of 
heuristic code to treat anything with "--" as internal? Of course. Would 
this have the net effect of raising false positives, confusing people, 
sparking endless angry emacs-devel threads, kicking your dog, and 
increasing bug reports? Absolutely.

This is not and was never part of my suggestion.

> > Also I just dislike computer heuristics.
>
> It's not a heuristic.

Okay.

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

This is outside the scope of this suggestion. For them, nothing changes.

So the objection I see is: if this explicit internal declaration were to 
be introduced, and say its scope is limited to the file in which it is 
declared, and then a programmer explicitly declares a function as 
internal knowing full well that this declaration means file-local, and 
that programmer then uses this internal function external to that file, 
they are rightfully triggering whatever ramifications the warnings are 
warning them against. See my alligator analogy.