3 ms·
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 whatev
by sukuriant 14y ago
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.
- hmottestad 14y agoActually, I do like reading javadoc. It's just a pain to create and the code feels a bit bloated with all those comments.
- chimeracoder 14y agoPython's is far superior to Javadocs. 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.
- ww520 14y agoI 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.