Pet Peeve #582: Bad Documentation

At work, I've been using GWT, and for the most part I've really enjoyed it. Occasionally though, I get frustrated by some things. For example AutoBean, a JSON-to-Java object parser for GWT, has almost no documentation. The Google Code wiki page is literal one of the only pieces of documentation out there, and it's quite bare. :/

Today I had to parse JSON lists using AutoBean. Here is the only relevant statement I was able to find:

List and Set properties are encoded as JSON lists. For example, a List<Person> would be encoded as:

[ { "name" : "John Doe" } , { "name" : "Jim Smith" }]

No information on how to go the other. Not cool. I had to do a lot of experimenting to find out that AutoBean only accepts something like this right now:

{ people=[ { "name" : "John Doe" } , { "name" : "Jim Smith" }]}

Hopefully this will be improved for the next release.

Also, there were very few code examples online. Open source software can be really cool in that they provide a lot of really useful tools, but their lack of support is quite frustrating. This is not to say that all open source software has horrible documentation, but in my experience, it is usually worse than the Proprietary equivalents. Just take a look at MSDN vs Oracle's Java documentation. Thankfully, a co-worker helped me find a workaround that he had used in a different project.

Anyway, time to learn everything to there is to learn about Flash/AIR/ActionScript 3. Our J3WAO sprint ends tomorrow, and we still have a lot (all) of our development left to do. :P