JavaDocs are great. They're the standard for api documentation, but as good as they are they have one big problem: all classes and all methods are created equal. This can be a problem especially in the quite verbose Java language. Sometimes one class or method is much better than another one. Sometimes you get overwhelmed by the options and have no idea where to even start looking.
Someone has come up with a solution and it's pretty good! It's called Jadeite and it was written four smart guys at CMU. They've even run it on the two common api docs already.
It introduces a few useful features.
- It weights classes based on usage. java.lang.Date is huge, java.sql.Date is not as big. This is a huge help when dealing with two similar looking classes that have very critical differences.
- Examples (only for constructors so far) that have been scavenged off of the Internet.
- Users can annotate the documentation as they use it with placeholders. This is a combination wishlist / alternative finder.
It's a huge time saver already. The features have added the best part of php.net's comments without all the noise. If you're doing Java or Groovy development, go check it out.
