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.
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.