Java docs are great because they document: * technical details and algorithms used * side effects * runtime and memory usage * inputs that result in undefined behavior * causes of exceptions * behavior when accessed concurrently * thoroughly hyperlinked

It's been this way for decades and the presentstion has remained largely consistent the whole time.

Second this. The core SDK and many common libraries are very well served by javadoc. I believe this is a key aspect of the success of Java. Javadoc serves so well that it compels Java developers to use it and you can tell if you're dealing with 'good' work or not by the thoroughness of the javadoc work.

Spring has often frustrated me in this regard. Spring's website is thorough and nearly everything you might need can be found there with enough wading, but Spring's javadoc is often lacking. You frequently run into placeholder entries and some of the key Spring packages and classes lack sufficient overview javadoc. Spring's indifference to javadoc is deeply stupid. I can think of several cases where Spring users have written suboptimal programs where they fail to utilize the platform properly, and I'm certain this happens in-part because Spring's javadoc fails to guide them.

One case I ran into in the last little while is a system that implements a configuration file template system; Spring properties substituted into templates used to generate multiple complex (not 'context') configuration files. Unless you read the walls of Spring website documentation you won't know that Spring already provides exactly that capability and so the coders involved wrote their own half-baked one.