Some apps may use large or indefinite numbers of databases, e.g. a database per document, and need a way to close a database to reclaim memory. (See this thread for instance.)
Also filed as couchbase/couchbase-lite-ios#429
I made the signature of the Obj-C method look like this:
- (BOOL) close: (NSError**)error;
The actual closing of the database can't fail, but it first saves changes to all CBLModel objects, and that might cause errors (most likely conflicts or validation issues.)
On platforms that use exceptions for signaling errors, this wouldn't affect the signature of this method, bu the docs should point out that it can fail if a model fails to save.