Re: declare function/macro private

[Paul W. Rankin]

On 2021-06-07 15:59, 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.
>
> I'm not sure which part of what you quoted made you think that I think
> you with to impose or change anything (other than add a new
> declaration, obviously).

Cool. This was not necessarily directed at you individually. I just want 
it be be crystal clear the limited extent of what I'm prepared to 
suggest/defend. Wording-wise, I wouldn't consider something like this a 
"change" in the sense of something existing that gets replaced with 
something else, but yes it's a "change" in the sense of something added.

> From that stand point the two discussions are orthogonal.  They only
> interact to the extent that they provide similar features so they are
> somewhat redundant.

In a way yes. From (info "(elisp) Tips for Defining"):

`PREFIX--...'
     The variable is intended for internal use and is defined in the
     file `PREFIX.el'.  (Emacs code contributed before 2018 may follow
     other conventions, which are being phased out.)

So right now it's just a tip that is supposed to communicate the 
author's intent. This is why I don't buy the idea that anyone could have 
used internal functions in multi-file packages -- because all they've 
done is followed a tip to communicate intent.

> > Trying to retroactively impose some definitive meaning upon people's
> > use of "--" is, as I said, the path to ruin.
>
> I disagree.  I've been in the business of slowly changing ELisp coding
> style for more than 20 years now, and while I'm not sure that what I've
> proposed here to do with "--" would work well, I'm pretty sure it would
> not be a path to ruin.

Okay perhaps not.

> > 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".
>
> I think most people who don't know better won't see any difference
> either after we'd introduce the new rule.  Or if they do, they'd then
> learn about it and either adjust their code or ignore the warning.
>
> > This is not and was never part of my suggestion.
>
> Of course not.  That was my suggestion.

I just really do not want to be caught defending the "--" idea against 
the hordes. I hope the rest of the thread can please consider that a 
wholly separate idea.

The idea of a `(declare (internal ARG))' seems an easier sell because it 
won't affect anyone who doesn't explicitly use it. It seems to open more 
possibilities for font-locking as Lars mentioned, and for generating 
info in the help buffer. Further to that, you could provide "levels" of 
how internal something should be treated, e.g.

(declare (internal t))  <- basic warning
(declare (internal "use `foo-public' instead."))  <- warning with hint
(declare (internal 'strict))  <- compiler signals an error, computer 
catches fire