Comment by brabel

I've written many APIs. Never have I got it right without first writing lots of tests, finding the rough corners, improving it... and so on. Writing documentation after that is absolutely mandatory for the end result to be a high quality API. As you write how it is meant to work, you will definitely find things that don't really make sense, or that should not be as hard ( I think this post shows just such an API that hasn't gone through this process ). IMHO documentation is NOT optional. The implementation is NOT how you mean for the API to be used.