Re: declare function/macro private

["Paul W. Rankin" via "Emacs development discussions." <emacs-devel@gnu.org>]

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