I've been looking around for this for a long time but can never seem to find it in the Android documentation. There's all sorts of advanced things I see, but I can never find any solid documentation - there's the shapes package, but it provides no insight on how to use them in xml. The best I can do so far is finding other people's examples.
Is there some magical documentation that exists for the XML shapes?
Well, this is only half an answer, but you could try poking around in the source code for the android.graphics package. In there you can find links to the java code for shapes, gradients and lots of other things. It's not XML documentation, but the XML is usually linked to the Java stuff, and you might be able to find what you're looking for in there. For example, here's where the java files for the Shape class are defined.
I decided to take it upon myself to track down all the code and figure out all the Drawable XML data myself. Here are the fruit of my labors...
The Missing Manual on Drawables XML
How the data was gathered:
It turns out the real meat of the code is in the android.graphics.drawables package, not android.graphics.drawables.shapes. Within the Drawable class there is a method createFromXml() which is the start of all Drawable XML file parsing. From there, it is relatively simple to trace how each type of Drawable is inflated from XML (via their inflate() methods).
I don't claim the documentation to be perfect or complete, but it's a lot better than anything else I've found online. Any suggestions would be welcome.
Not sure if this is new since your post, but there is some complementary documentation on the official Android developer site at:
http://developer.android.com/guide/topics/resources/drawable-resource.html
Dave