Agreed! The API should basically document itself. If you have to provide long examples of how to do something then there is a good chance the API isn't that good. Easy to use for developers makes a platform more stable and produces better quality apps, IMHO.