[PCBC-165] Docs have return type scalar ( Binary object ), which doesn't help much Created: 14/Dec/12  Updated: 30/Jan/13  Resolved: 30/Jan/13

Status: Resolved
Project: Couchbase PHP client library
Component/s: docs
Affects Version/s: 1.1.0
Fix Version/s: None
Security Level: Public

Type: Improvement Priority: Major
Reporter: Tim Smith (Inactive) Assignee: MC Brown (Inactive)
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified
Environment: http://www.couchbase.com/docs/couchbase-sdk-php-1.1/api-reference-summary.html


 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.


 Comments   
Comment by Tim Smith (Inactive) [ 19/Dec/12 ]
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!
Comment by MC Brown (Inactive) [ 30/Jan/13 ]
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.
Generated at Sat Oct 25 12:28:30 CDT 2014 using JIRA 5.2.4#845-sha1:c9f4cc41abe72fb236945343a1f485c2c844dac9.