[PCBC-165] Docs have return type scalar ( Binary object ), which doesn't help much

Wed, 30 Jan 2013 07:50:26 -0600

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.

Couchbase

[PCBC-165] Docs have return type scalar ( Binary object ), which doesn't help much