There are reasons why you might pursue a different API style, but it would be nice if you were super-clear on the contract. Can we always rely on good values in the NSError object here, or do we need to check CBLQueryEnumerator first? I’m assuming not, since I don’t see a good way to check CBLQueryEnumerator for failure.
So I guess that to check for errors, you check the NSError first, and then check the CBLQueryEnumerator after that if the NSError shows no error?
I did see that CBLQueryEnumerator is an Obj-C class, and I’ve seen the nil-check approach (although it feels far less common to me in Cocoa APIs anecdotally, and I don’t have a great way of analyzing all the APIs for frequency). Still, it does feel like good fit when you have a natural return value that isn’t a success/failure boolean, which in this case you do.
Since the error-handling approach wasn’t documented for the method, and I couldn’t find either a description or a really conclusive example of error-handling with CBLite and with the methods I was invoke in particular, I wasn’t sure what approach you were using. Thanks for clarifying which approach you’re using, this’ll help me handle errors properly. Is this covered already in the documentation and I just missed it, or is this something that’d be a valuable addition?
I don’t see a need to add explicit information about error handling because we’re not doing anything differently than usual. (I haven’t seen this sort of information in documentation of other 3rd party APIs. And no one’s asked about this before you did, in the 4 years that some version of Couchbase Lite has been available.)
Here’s the declaration of the closest equivalent method from Core Data, on NSManagedObjectContext. Note that it works exactly the same way as ours:
If an error occurs, returns nil. If no objects match the criteria specified by request, returns an empty array.
Similar phrases appear in the other APIs you reference here.
Assuming you do want your API documentation to document your API, this seems worth adding. It’s part of how the API behaves, it’s an extremely small addition, and similar documentation exists in other APIs.
Anyway – I have the answer I need, the documentation is up to Couchbase and I’ll move on.
I don’t see the need to add an explicit section of the developer documentation detailing error handling.
I do agree that it would be good to give each method’s doc-comment a full descriptions of parameters and the return value. A few methods have those already (search the headers for @return) and you’ll see that those comments describe the return values that indicate errors. I haven’t done this for the whole API mostly due to time constraints. To be honest, a lot of developers don’t seem to look at the doc-comments at all…