I have been very frustrated in the past when the only documentation provided was javadoc. In many cases there was an xml that was not documented very well, and

I have been very frustrated in the past when the only documentation provided was javadoc. In many cases there was an xml that was not documented very well, and subtle things about the classpath that kept the system from working. Often the javadoc is just regurgitating the name of the method. In many cases the javadoc reminds me of the help systems in windows programs. I think I remember seeing a discussion on reddit where they were asking if anyone had ever found an answer in a windows help topic.