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

[Elias Ross (JIRA)]

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)
            Reporter: Elias Ross
         Assigned To: Manik Surtani


>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.

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://jira.jboss.com/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira