Uploaded image for project: 'Couchbase .NET client library'
  1. Couchbase .NET client library
  2. NCBC-73

Need better explanation of usage and return values of increment operation (and likely others)

    Details

    • Type: Bug
    • Status: Resolved
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: 1.1.6
    • Fix Version/s: 1.3.2
    • Component/s: docs
    • Labels:
      None

      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.

      No reviews matched the request. Check your Options in the drop-down menu of this sections header.

        Activity

        Hide
        jmorris Jeff Morris added a comment -

        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.

        Show
        jmorris Jeff Morris added a comment - 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.
        Hide
        jmorris Jeff Morris added a comment -

        Resolved the major issues with documentation. Perhaps create another ticket for any additional changes that need to be made?

        Show
        jmorris Jeff Morris added a comment - Resolved the major issues with documentation. Perhaps create another ticket for any additional changes that need to be made?

          People

          • Assignee:
            jmorris Jeff Morris
            Reporter:
            perry Perry Krug
          • Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Gerrit Reviews

              There are no open Gerrit changes