What does the internal meaning in function names in Emacs Lisp mean?

Question

Some people use a double dash to indicate that a function can be changed: What does the double (-) convention in function names mean in Emacs Lisp

Does including internal in function names include similar things?

Two examples

 where-is-internal internal-make-var-non-special 

The where-is-internal function has a detailed document and is mentioned in the manual. Is a where-is-internal exception thrown?

Is there a difference between having -internal as a suffix and having internal- as a prefix?

Adding to the confusion, there are also function names with internal-- (with a double dash) as a prefix.

Answer 1

The confusion lies not only in the naming convention (variability due to history and, perhaps, sometimes a whim). The confusion lies in the very concept of “internal” in free software, where the source code is open to all to use or modify (even fork) as it sees fit.

To answer your question from the point of view of Emacs Dev and, therefore, from the point of view of the main intention: “internal” means that someone using this function is likely to face future changes in the implementation of Emacs-Dev and use of this function, than it can take place for not "internal" function. IOW, you may not want to rely on him to remain as he is now. It's all.

But there is a lot of "maybe", "more likely" and "maybe" there. In practice, some non-"internal" functions change more radically or faster than some "internal" functions. Perhaps for the first there will be a period of grace period, during which the situation with a preliminary change is allowed, i.e. Still working. This may not be the case for something "internal." But then again, in practice there is a gray color between the black “inner” and the white “inner”.

Someone from Emacs Dev (e.g. @Stefan) might put this in a different way or correct my interpretation.

My own approach: sometimes (often) there were functions and variables that the author did not expect from users to use directly, and therefore, of course, was considered "internal", which users nevertheless used for good use, or even "was" for use (modulo rewriting a large amount of code). Some of them deleted their "internal" status (no, I have no examples remembered). Or sometimes a new, non-“internal” function is added to make the behavior available - for example, a shell argument or a function argument is added (again, I don't have non-standard examples).

IOW, for Emacs Dev it’s also not always clear what should be considered “internal”. Just take the label as a flag, which you might not want to rely too much on this function or variable.

What are the different notations: My impression is that the agreement has been used more recently (although there is an old code that uses it); using internal is an older convention, for the most part.

Answer 2

The “internal” and “-” agreements are similar. In fact, "internal" is used when there is no prefix after which you can put a double dash (which is usually the case for functions implemented in C).

And yes, as Drew explains, the intention underlying the concept of “internal” is to encourage people not to use it directly. IOW, if they need the appropriate functionality, they should report an error requesting that its status be “non-internal”.