Shared publicly  - 
 
Is anyone still following me who actually intends to be following +Google Guava instead? Just a reminder that that is there.
 
Guava users:

When it comes to Javadocs, can there be "too much of a good thing?"

Lately, I've been tending toward writing class documentation that is rather... long. A few examples:

http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Multimap.html
http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/hash/HashFunction.html
http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html

The question is about where this information really belongs. Each of these also links to the relevant page of the GuavaExplained wiki, which can contain any information it wants to as well. So what information belongs in javadoc and what belongs in wiki? How could we define the dividing line?

Keep in mind that javadoc is prone to one kind of staleness (one of us notices a problem but doesn't bother to submit a code change, but would have edited the wiki), while the wiki is prone to another kind of staleness (the code changed and we remembered to update the javadoc, but forgot to go edit the secondary docs).

We'd like to hear your suggestions, and please also +1 the suggestions of others that you agree with!

--+Kevin Bourrillion
1
David Beaumont's profile photoKevin Bourrillion's profile photo
3 comments
 
I think that the Wiki level documentation is very useful for higher level documentation where what you want to say isn't neatly bucketed by class or package. Things like "why should I consider using ImmutabeXxx classes?" should live there (that's stable information, relatively free from detail and shouldn't rot so quickly). But the Wiki should reference the JavaDoc directly when there's need for detail and the JavaDoc should reference the Wiki for overviews.

Learning new APIs is hard and (for me) having some overall dicsussions of why things are where they are and why certain patterns were adopted is really useful.
Add a comment...