On Thu, Jul 3, 2014 at 4:27 PM, Eric Rubin-Smith <eas....@gmail.com> wrote:
> I respectfully re-raise my issue. The "TLDR" is that the C API docs are > critically lacking in specificity in a relatively wide range of areas, as > exemplified below, making it difficult to write correct clients against the > library. Do the SQLite authors disagree with my below points about the API docs for > sqlite3_step(), sqlite3_exec(), and sqlite3_prepare_v2()? I think the > criticisms can be extended to other API calls. If the authors do not > disagree then can we create a ticket against the docs? > (disclaimer: i'm not one of the authors) While i do fundamentally agree with your points, in practice it's not as difficult as you seem to be making it out to be. The rule is really simple: any non-0 code is an error unless the APIs specify otherwise, and the step() API does indeed document 2 non-error, non-0 error codes (SQLITE_STEP and SQLITE_DONE). Anywhere else in the API, non-0 means Bad News. There are relatively few cases (locking comes to mind) where an error returned due to something other than a misuse of the API should be considered recoverable (IMO). The fact that (literally) millions of applications get written despite any perceived shortcomings in the documentation suggests that the docs are at least "adequate," if not "perfect." -- ----- stephan beal http://wanderinghorse.net/home/stephan/ http://gplus.to/sgbeal "Freedom is sloppy. But since tyranny's the only guaranteed byproduct of those who insist on a perfect world, freedom will have to do." -- Bigby Wolf _______________________________________________ sqlite-users mailing list sqlite-users@sqlite.org http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users