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

[Manik Surtani (JIRA)]

    [ http://jira.jboss.com/jira/browse/JBCACHE-939?page=comments#action_12351010 ] 
            
Manik Surtani commented on JBCACHE-939:
---------------------------------------

Agreed, this is due for a revisit.  In fact, in the process of reorganising overall documentation, examples and tutorials; javadocs is a part of that (although not explicitly as a separate JIRA task).  Since you've added this will attach it as a dependency.

> 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