Since Android is open-source, anyone can look at the code and see how it works inside. If you do this, you'll notice that most but not all of the APIs are publicly documented.

If they're publicly documented, they're part of what we consider the Android Application Framework. This means their tests appear in the Compatibility Test Suite (CTS) so that our hardware partners have to prove that the APIs work, and that we promise to try very hard not to change them and thus break your code.

In almost every case, there's only one reason for leaving APIs undocumented: We're not sure that what we have now is the best solution, and we think we might have to improve it, and we're not prepared to make those commitments to testing and preservation.

We're not claiming that they're "Private" or "Secret" - How could they be, when anyone in the world can discover them? We're also not claiming they're forbidden: If you use them, your code will compile and probably run. And in fact we know of quite a few apps out there whose developers have used undocumented APIs, often to good effect. It's hard to get too upset about this in cases where there's a useful API that we haven't gotten around to stabilizing.

But the developers who use those APIs have to be prepared to deal with the situation that arises when we move them from the undocumented outside into the Android Application Framework. Fortunately, this is reasonably straightforward. Also we take a close look at Android Market, using our in-house analytics tools, to get a feel for the impact when we know one of these changes is coming.

There are a few such changes coming up in the Android 4.0 "Ice Cream Sandwich" (ICS) release of Android. We wanted to take the opportunity to combine these words on undocumented APIs with some specifics about the changes.