Java Docs For Libraries

(from WhyJavaIsGreat)

Java is famous for its libraries. Whatever the newest, most cutting edge technology out there, it's probably implemented in at least one Java library (actually, there's a good chance that the reference implementation is a Java library) that's easy to drop into your own programs.

A big reason for this is the current popularity of Java. But I'd argue that JavaDoc is a significant and often overlooked contributor to Java's "library culture". It's practically guaranteed that a publicly-available Java library will include extensive javadoc comments. It's not just that the technology is available, but that there's a culture that expects useful javadocs; libraries without good javadocs are considered beneath contempt. (I'm looking at you, IBM alphaworks programmers!)

You can argue (correctly) that JavaDoc is a mere shadow of true LiterateProgramming, but the automatic creation of documentation with a featureful and standard interface is a huge benefit to developers with a need for a library. Docs for libraries in other languages like POD and pydoc tend to be extremely sparse and simplistic by comparison. I'd go so far as to argue that the ease of learning from javadocs leads to more code reuse in Java than in other languages.

My experience of the perl and java communities is that perl has far more code reuse, in part due to POD (PlainOldDocumentation?, which by the way also is automatic creation of documentation with a featureful and standard interface, albeit not as good as javadoc) , but mostly due to the ComprehensivePerlArchiveNetwork. --ChristofferHammarstrom

CategoryJava