On the use of of 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"}

The Mathematica guidebook for programming By Michael Trott, page 494 says on the Internal context

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

Also, here is a mention of Bag functions:

Implementing a Quadtree in Mathematica

But since I've seen number of Mathematica experts here suggest Internal`Bag functions and use them themselves, I am assuming it would be sort of safe to use them in actual code? and if so, I have the following question:

Where can I find a more official description of these functions (the API, etc..) like one finds in documenation center? There is nothing now about them now

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

If I am to start using them, I find it hard to learn about new functions by just looking at some examples and trial and error to see what they do. I wonder if someone here might have a more complete and self contained document on the use of these, describe the API and such more than what is out there already or a link to such place.

Answer 1

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

This means, among other things, the following things hold about anything you might find in there:

• You most likely won't be able to find any official documentation on it, as it's not meant to be used by the public.
• It's not necessarily as robust about invalid arguments. (Crashing the kernel can easily happen on some of them.)
• The API may change without notice.
• The function may disappear completely without notice.

Now, in practice some of them may be reasonably stable, but I would strongly advise you to steer away from them. Using undocumented APIs can easily leave you in for a lot of pain and a nasty surprise in the future.