Can't See the Wood for the Trees?
Javadocs are a great step forward in creating self documenting code, however, with any non-trivial project the number of classes can be overwhelming. New programmers nto the project need a guiding hand to navigate the large code base. When I look at 3rd party products, I want a simple "Hello World" example, of how it works, and then I want to know which classes are the "core" classes. I also want to know which methods on those classes are the most important.
Take Java's Swing classes for example. I want to be shown that JFrame is the place to start, as all other components will be placed within a JFrame. Then I want to be show a few common components, such as JLabel and JTextArea.
This is where, IMHO, the javadocs are not fit for purpose. Look at JLabel. After the useful pre-amble, the next thing we see is a list of nested classes that virtually nobody cares about. Then we are confronted with a bewildering list of methods, that are mostly unhelpful. A useful API document would highlight the most useful methods : setText and getText. The least useful methods can be hidden, or at least placed later in the document.
My solution to this is PriorityDoc. Each method can be given an importance (a number from 1 to 5). When browsing the API, I can choose how much of the API I wish to see. As a newcomer to the API, I will browse only the most important methods (Level 1). As I become more familiar with the code base, and wish to use more of its features, I will start browsing at levels 2 or 3. If I want to see everything, then browsing at level 5 will show every detail.