[jbosscache-dev] comments on 2.0 BETA1 documentation

[Galder Zamarreno]

Hi,

Over the weekend, I read the documentation for 2.0 BETA1 taken from http://tinyurl.com/36q634. Here are my comments:

Preface
- 2nd paragraph, "when" should start with capital letter.
- "information around this" might sound better "information about this"
- "use the JBoss Cache as a clustering", I would remove "the"
- 3rd paragraph, "it's" should "its"

1.1. 
- "JBoss Cache... from JBoss Cache", it sounds like a repetition.
- "is" repeated

1.2 
- Lists lines don't have dots at the end of line, they do in previous section; consistency preferred.
- "A The Cache is organised as a tree..."; remove The
- "propagate any changes to all other replicated trees". Maybe you wanna make a brief intro to buddy replication?
- Last paragraph, last sentence, "will be discussed" seems out of place, "more on this later" sounds better to me.

1.3. 
- Only some of the dependencies noted. Either list all or say that these are some of them.

2.2 
- 1st paragraph, 2nd line, "is" repeated.

2.4 
- A code example using Option might be useful?

3.5 
- Mention c3p0 in JDBCCacheLoader within the list of shipped implementations

4.1. 
- Comma missing after "CacheFactory and,"

4.2.
- "is run" should be "runs"
- Second paragraph, it might be better to refer to server's lib directory rather than /lib dir in case people confuse it with root /lib

4.3.
- It might be worth noting binding to JNDI allows the cache to be accessed remotely via the invoker specified.

4.5.3
- It might help adding imports to second code example

4.5.4
- Second paragraph, addition spelled incorrectly

6.1
- Last paragraph, should be "Any modifications"

6.4.3
- It's SingletonStoreCacheLoader not, SingletonCacheLoader

6.5.3
- Disabling jboss serialization is done with "-Dserialization.jboss=false". All JBoss properties follow the "jboss.x" notation, should we follow similar for this as well?

7.1.2
- Same as in 1.2, this section will mention buddy replication so you might wanna reword starting sentence?
- Is it worth mentioning when is replication queue recommended using? I.e. REPL_ASYNC without TXs?
- 3rd paragraph, "applie at all nodes", sounds better "applied to all nodes"
- 3rd paragraph, "this is not be the case", is this correct? "this might not be the case" sounds better to me.

7.1.2.2.3
- "My default" should be "By default"

7.3.1
- We need consistency on how configuration parameters are written, whether monospaced or not and whether to start them with capital letters or not. See last line in first basic type and 2nd paragraph in 2nd basic type. 
- In state transfer types, CacheLoaderPreload is the old fashion way to define preloading.
* There's a few of these in the CacheLoader section too.

7.3.2.
- "2." section, "Here" should be "Here," ?
- "3." Section, 3rd line, "it's" should be "its"

8.1. 
- "For example, here a database CacheLoader" does not sound alright, maybe punctuation change?

8.2. 
- 2nd paragraph, is the "Note that," located in the right place, the paragraph is talking about CacheLoader class

8.2.
- <shared> is not explained here, maybe it's worth noting that it's explained later in the Strategies section?

8.3.
- It might be worth mentioning the package where these implementations are located. All of them are under o.j.c.loader except Bdje and Jdbm.
- I have just realised that it's only JDBCCacheLoader that is currently using VAM instead of serialization. Bdje and Jdbm do their own way, but FCL is still using normal serialization. I guess we want FCL to use VAM as well, correct?

8.3.1.
- "adding check.character.portability" is supposed to be added to the properties element. This should be noted.

8.3.4
- Paragraph before last, first line, should be "instances"

8.5.4
- "When used with a transactionm anager" should be corrected

9.1.1
- policyClass explanation should start with "this is required" and "one os not defined" should be corrected.

10.1.
- first line, should be "its" rather than "it's"

10.1.1.
- Maybe we should mention how we acquired WL locks when inserting/removing children?

10.1.3.1
- should be "its workspace" rather than "it's workspace"

10.1.3.2
- "representation" rather than "reporesentation"

10.2.
- Shall we mention that GenericTMLookup will fallback in DummyTM if it found none?

11.2 
- Same as we recommended InitialStateRetrievalTimeout should be longer than LockAcquisitionTimeout, we should say the same for SyncReplTimeout.
- UserInterceptorMBeans: mbeans in lower case, we should be consistent and write it the same way in the document, as MBean(s)

12.2.
- Change CacheListener events to be the same as the enums defined in CacheListenerEvent.ListenerMethod, shouldn't it?

Cheers,

Galder Zamarreño
Sr. Software Maintenance Engineer
JBoss, a division of Red Hat