Sub-docs documentation misleading

The 'Maintaining Data Consistency' paragraph of our documentation seems to be misleading (http://developer.couchbase.com/documentation/server/4.5-dp/sub-doc-api.html)

Sub-document APIs do not require the use of CAS when updating single fields

This is not entirely true. CAS describes the consistency regarding the client side state (The consistency term is overloaded and a sub-document operation indeed leads to a valid state for a document on the server side. So you could argument that the data itself is consistent, but this has nothing to do with CAS). This sentence give the impression that CAS would be in general not required, but this is not true. If two clients would update the same sub-document nearly same time based on an earlier state of this sub-document then there would be a conflict and it would be required to handle this conflict the same way as you would need to handle such a conflict by doing a normal replace (w/o using the sub-document API). So sub-document does not add additional consistency in general. If the previous state of the sub-document doesn't play a role then the sub-document API brings indeed an advantage (e.g increasing a counter value or appending a value to an array without requiring to reuse this values later for further updates)

The application logic may require a document modification to be either:

Locally consistent with regards to the immediate parent object which contains the value being modified. For example, ensure that a specific object key is unique, or ensure that a specific list item is not duplicated.

Globally consistent with regards to the entire document. For example, if the existence of one field in the document only makes sense when another field is in a specific state.

In Couchbase Server 4.1 or earlier versions, both these scenarios require the application to make use of CAS to ensure consistency. With the sub-document API model, the local consistency requirement does not require CAS as the server can ensure that the data is consistent atomically. For global consistency requirements, the SDKs may employ CAS to ensure that a document's state has not already changed.

What does this mean? The documentation might be clearer. E.g. "ensure that a specific object key is unique, or ensure that a specific list item is not duplicated" might be a data consistency criteria, but this is a criteria the application defines. The sub-documents would e.g. allow to append the same value twice to an array. The CAS value would be used in order to handle the concurrent access and so is more relevant regarding the state consistency.