Joe's Java and Web Jottings

your host


Your Host

Calendar

««Nov 2009»»
SMTWTFS
1234567
891011121314
15161718192021
22232425262728
2930

My Top Tags

               

Java Libs and Tools

My Other Pages

My RSS Feeds








Javadoc : Use the "-use" tag at all times

posted Wednesday, 7 May 2003
Javadoc should have "-use" on by default. APIs such as the Jena RDF package from HP have relatively complex hierarchies of related items. One of those is the standard interface plus implementation separation, similar to JDBC and most Jakarta Commons kits.

The trouble with those APIs is that its hard to tell just by looking at the interface as to how one should use it.
Does one


  1. Instantiate the Impl classes directly?
  2. Use a Factory?
  3. Acquire them through using other already instantiated classes acquired by #1 or #2 (ala JDBC, where ResultSet comes from Statement which comes from Connection which comes from Driver, all of which is behind the scenes to the programmer).

One should be able to look at the javadocs to see this. But one has to be able to do "reverse lookup" to do it, as in "ok, here's a [interface] that seems to have what I need, so how to get one, and click on "Use" to find public implementations and/or classes that return instances of that interface, so one can drill up to find the correct starting point for the API.

Leave off "-use" in your javadoc command and one has to click through every single package and almost every single class to try track down where it comes from. If there's a user's guide to look up, then its (a little tiny bit) less important, but having -use makes it so easy...

So everybody making public javadocs to distribute with your software: include the -use in the build instructions, ok?