Re: declare function/macro private

[Paul W. Rankin]

> On 6 Jun 2021, at 7:53 pm, Lars Ingebrigtsen <larsi@gnus.org> wrote:
> 
> "Paul W. Rankin" via "Emacs development discussions."
> <emacs-devel@gnu.org> writes:
> 
>> Given we have a function/macro declare interactive-only property,
>> would it be worthwhile to consider a `private' property?
>> 
>> Of course there's already the convention of
>> prefix--my-private-function, but 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.
> 
> The compiler could do this with "--" symbols if we wanted to, I guess.  
> 
>> e.g. in foo.el:
>> 
>> (defun foo-private ()
>>  (declare (private "use `foo-public' instead."))
>>  ...)
> 
> I'm not necessarily against this or anything, but I do like the "--"
> convention, because it makes it very explicit what's internal and what's
> not.  On the other hand, if we had tagging like this, we could also
> make (say) font-lock react to this information and make it as obvious as
> the "--" convention.

Ah cool, I didn't think of font-lock, but that would be great if a function 
declared as internal appears outside of its program then it gets highlighted in 
font-lock-warning-face. Then the curious programmer calls `C-h f' on it and the 
help buffer could show e.g.

  This function is internal to <library> and should not be used
  in other lisp programs. Use <other-function> instead.

The "--" convention is fine and I wouldn't suggest to change/replace this; it's 
clear to people what it means once they've learnt what the convention means.

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.

Also I just dislike computer heuristics.

I'll revise the initial suggestion from `private' to `internal' since that's 
more the Emacs lexicon, i.e.

  (declare (internal t))
  (declare (internal "use `other-function' instead."))