[NCBC-73] Need better explanation of usage and return values of increment operation (and likely others) Created: 26/Jun/12  Updated: 30/Jan/14  Resolved: 30/Jan/14

Status: Resolved
Project: Couchbase .NET client library
Component/s: docs
Affects Version/s: 1.1.6
Fix Version/s: 1.3.2

Type: Bug Priority: Major
Reporter: Perry Krug Assignee: Jeff Morris
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   
The current docs for incrememnt: http://www.couchbase.com/docs/couchbase-sdk-net-1.1/couchbase-sdk-net-update-increment.html

Can there be some attention paid to the above documentation (and will likely be needed across the board in similar areas):
-Some return values say: CasResult<ulong> (Cas result of bool). What is "Cas result of bool"?
-Other return values say: IMutateOperationResult (Mutate operation result). Is the same operation really expected to return drastically different object types?
-Some examples have "var casv = client.GetWithCas("inventory");" before performing the increment. Is it necessary to get the CAS id before performing this type of increment? Is it necessary to supply the CAS id for this type of increment?
-Some examples have very simply usage, others have more detail:
var getResult = client.ExecuteGet("inventory");

if (getResult.Success) {
var mutateResult client.ExecuteIncrement("inventory", 100, 1, getResult.Cas);

if (mutateResult.Success) {
logger.Debug("New value: " + mutateResult.Value);
}
}

-Can all of the examples be made consistent, and/or just have a single example at the top showing how to perform the incremement and work with the result. Then the various optional methods can be shown below?
-There seems to be a fair amount of duplication within the methods provided. For example, the last two are exactly the same (even have the same typo on "numvers") and there are other seemingly duplicates throughout.

 Comments   
Comment by Jeff Morris [ 30/Jan/14 ]
Addressing a few points from above:

>>Some return values say: CasResult<ulong> (Cas result of bool). What is "Cas result of bool"?

Changed to "`ulong` the result of the value decremented by the offset (if the default value has not been stored, it will be the default value)". This will be included in the 1.3.2 release.

>>Other return values say: IMutateOperationResult (Mutate operation result). Is the same operation really expected to return drastically different object types?

Yes, their are two 'forms' of operations exposed by the 1.X version of the SDK: one's that return the explicit result of the operation (true/false/integer/etc) and one's that return a 'richer' object which includes the StatusCode, whether or not an exception occurred, the explicit result of the operation, etc. The former have a naming convention with that matches the operation (e.g. Increment, Decrement, etc) and the former are named Execute[Operation] (e.g. ExecuteIncrement, ExecuteGet, etc). The former were added after the fact so that they wouldn't change the interface of the API, which would be breaking changes for clients, while adding much needed 'meta-info' about the operation's status.

>>Some examples have "var casv = client.GetWithCas("inventory");" before performing the increment. Is it necessary to get the CAS id before performing this type of increment? Is it necessary to supply the CAS id for this type of increment?

Yes, that was how the API was designed. We will investigate more intuitive means of using CAS in 2.X version of the SDK.
Comment by Jeff Morris [ 30/Jan/14 ]
Resolved the major issues with documentation. Perhaps create another ticket for any additional changes that need to be made?
Generated at Fri Aug 22 21:32:30 CDT 2014 using JIRA 5.2.4#845-sha1:c9f4cc41abe72fb236945343a1f485c2c844dac9.