The main thing I've noticed with the most useful API documentation is that it was written by a human. Lots of tiny examples also help. Whereas the auto-generat

The main thing I've noticed with the most useful API documentation is that it was written by a human. Lots of tiny examples also help. Whereas the auto-generated Java Docs are some of the most useless docs I've ever seen. I know thet can be improved, but generated the docs from the code is a good way to stop people from updating the docs... As now they have to update the code as well...