Hey now. I find Javadocs to be among the easiest to read formats of all the different documentation styles. Right up there with Python's standard one (or whatever tool python's default library as well as numpy and scipy use), maybe even better.
JavaDocs is one of the earliest (popular) standard tools for documentation, so I'll give it that, but it suffers a number of problems - problems which are partly relics of the Java language, but that's no excuse.
JavaDocs is too focused on documenting classes, rather than documenting functionality (Python docs, by contrast, focus on modules, which are themselves arbitrary chunks of code with connected functionality).
JavaDocs doesn't make the package/class hierarchy terribly clear - this is intrinsically tied to Java's overcomplicated class hierarchy and needlessly complicated package system, but it carries over into poor documentation as well.
JavaDocs also doesn't have a culture of providing complete examples of code, which exacerbates the two aforementioned problems.
That said, JavaDocs has inspired other good tools, so I'll give it some credit for that and write these criticisms off as vestiges from a time long past.
I found Javadoc well better and more informative than Python doc. Python module is nothing but a watered down version of a static class, so whatever applied to a class, you can say the same thing on a module.
