Uploaded image for project: 'Couchbase PHP client library'
  1. Couchbase PHP client library
  2. PCBC-165

Docs have return type scalar ( Binary object ), which doesn't help much

    Details

      Description

      A lot of the PHP methods are documented to return scalar ( Binary object ), which is not very helpful. What does the binary object represent?

      For example, the set method:

      http://www.couchbase.com/docs/couchbase-sdk-php-1.1/api-reference-store.html#table-couchbase-sdk_php_set

      What does it really return? By looking at the source, I think it returns bool(false) if it fails, and the new CAS id for the item (represented as a string in decimal notation) on success. Saying "Binary Object" is a long ways away from understanding this. The docs (and probably the underlying code, too, but hey, it's PHP and bound to turn into spaghetti, right?) need to create meaningful names for these things, like "Returns: CAS id string or false", and then use those names consistently.

      Another example, just below, is setMulti:

      It returns a PHP Array, where the index of the array is the key that was set, and the value is – I think – a CAS id string or false. I could be wrong here, I didn't do a complete test on it. But I think that demonstrates exactly the point. Currently it's very difficult for anyone to use the library correctly based on our API reference.

      The tests in the source code are a helpful source of info in the mean time, until the reference docs can be improved.

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

        Activity

        Hide
        mccouch MC Brown (Inactive) added a comment -

        I've updated the PHP documentation and tables to be more precise about the information/data return from each call, the possible exceptions raised during the process, and I've provided a list of the error codes for PHP responses. There is some further work to do to ensure the links between the elements are complete, and I should be completing that shortly.

        Show
        mccouch MC Brown (Inactive) added a comment - I've updated the PHP documentation and tables to be more precise about the information/data return from each call, the possible exceptions raised during the process, and I've provided a list of the error codes for PHP responses. There is some further work to do to ensure the links between the elements are complete, and I should be completing that shortly.
        Hide
        TimSmith Tim Smith (Inactive) added a comment -

        See related bug PCBC-170 "Document error code, etc.". Return type and error code are related, and both need to be exhaustively documented, but they're not exactly the same thing.

        Thanks!

        Show
        TimSmith Tim Smith (Inactive) added a comment - See related bug PCBC-170 "Document error code, etc.". Return type and error code are related, and both need to be exhaustively documented, but they're not exactly the same thing. Thanks!

          People

          • Assignee:
            mccouch MC Brown (Inactive)
            Reporter:
            TimSmith Tim Smith (Inactive)
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Gerrit Reviews

              There are no open Gerrit changes