[jboss-jira] [JBoss JIRA] Updated: (JBCACHE-939) Improve the quality of JavaDoc for JBossCache

Improve the quality of JavaDoc for JBossCache --------------------------------------------- Key: JBCACHE-939 URL: http://jira.jboss.com/jira/browse/JBCACHE-939 Project: JBoss Cache Issue Type: Task Security Level: Public(Everyone can see) Affects Versions: 2.0.0.ALPHA2 Reporter: Elias Ross Assigned To: Manik Surtani Fix For: 2.0.0.BETA1 From a beginner's perspective, the basic interfaces introduced in JBoss 2.0 do not explain their relationship very well. There are also too few API (almost no) usage examples. E.g., from Cache.java: * This is the central construct and basic client API of JBoss Cache and is used for * cache-wide operations. Describing an interface "Central construct" tells a reader almost nothing about how to use or how to implement this important class. So how is a user to understand that really it is a API for accessing different Node objects in a Tree? How does a user generally approach dividing their cache entities into Node objects? I'm working on cleaning the 2.0 classes up, following http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html as an example. Mostly, it's critical that the main interfaces (Node, Cache, CacheFactory, Fqn, CacheLoader) are documented really well. Also missing is CacheException. Which methods can this exception be thrown and for what reasons? Anyway, things to watch for: 1. Does the first sentence explain what it does or is. "For use cases that have an external representation and storage of data objects, doing a put() in the cache should not have as strong a set of semantics as though when the cache is in itself the main form of storing data." does not explain Cache#putForExternalRead. 2. Following sentences qualify the behavior.