Re: declare function/macro private

[Paul W. Rankin]

> On 7 Jun 2021, at 4:05 am, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>> 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:

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


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

> I think the "--" convention actually includes an extra information
> compared to yours which could be useful here: we could warn for uses of
> "foo--" if and only if the use appears in something whose name doesn't
> start with "foo-".
> 

> IOW, use the string before the "--" as the definition of the "library"
> (so that would support cases where a library is spread over several
> files, as well as the case where a single file contains "internal
> libraries").
> 
> Of course, if we enable such a warning now, we'll get a fairly large
> number of warnings, I think ;-)
> 
> Another advantage of the "--" convention is that you don't need to load
> the definition of that function in order to discover that it's private.

I'm not suggesting to do away with using "--" as a handy visual marker. I use 
that too.

I would caution that trying to introduce a heuristic approach to interpret 
human intent from just "--" in a symbol name is the path to ruin.

As for the case of "libraries" over separate files, again it's probably best to 
use the word "file" instead of "library" to define the limits of the 
suggestion; consider declare-function as corollary:

  Tell the byte-compiler that function FN is defined, in FILE.

And `(declare (internal t))' would be:

  Tell the byte-compile that this function is internal to this file.