About using Internal`Bag and any official documentation?

Question

(Mathematica version: 8.0.4)

lst = Names["Internal`*"]; Length[lst] Pick[lst, StringMatchQ[lst, "*Bag*"]] 

gives

 293 {"Internal`Bag", "Internal`BagLength", "Internal`BagPart", "Internal`StuffBag"} 

Programming Math Guide Michael Trott, p. 494 talks about the internal context

"But, similar to the Experimental context, there is no guarantee that the behavior and syntax of functions will still be available in later versions of Mathematica."

In addition, the Bag function is mentioned here:

Implement Quadtree in Mathematica

But since I saw that the number of Mathematica experts here offer the Internal`Bag functions and use them myself, I assume it would be safe to use them in real code? and if so, I have the following question:

Where can I find a more formal description of these functions (API, etc.), how can I find it in the documentation center? Now there is nothing about them.

 ??Internal`Bag Internal`Bag Attributes[Internal`Bag]={Protected} 

If I start using them, it will be difficult for me to learn about the new features, just by looking at some examples, trial and error, to see what they do. I wonder if someone here can have a more complete and self-sufficient document on the use of this data, describe an API and more than what it already is, or a link to such a place.

Answer 1

The Internal context is exactly what its name says: for internal use by Wolfram developers.

This means, among other things, something that you can find there, in the following things:

• Most likely, you will not be able to find any official documentation, since it is not intended for public use.
• This is not necessarily as important as invalid arguments. (A kernel crash can easily happen on some of them.)
• APIs are subject to change without notice.
• The function may completely disappear without notice.

Now, in practice, some of them may be quite stable, but I would strongly advise you to avoid them. Using undocumented APIs can easily leave you with pain and an unpleasant surprise in the future.