I completely agree. What I want 99% of the time is basically a Javadoc showing the methods, the inputs, and the outputs, and all of the types. And if there's a short summary and an example as supplemental material, that's great.

Unfortunately, developers seem to think their contrived examples are a stand-in for actually documenting the methods. I deal with a lot of Javascript libraries like this and it drives me insane.