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
Shared publiclyView activity