> So, given valid a valid statement pointer and a valid column index, a NULL pointer is returned in case of memory allocation failure, and probably some other cases. IMHO, mentioning that would improve the documentation. Again, it's just a matter of preference. I prefer explicit docs, but that's just my opinion. I see that last sentence as reaching an important consideration. How completely the range of API inputs and outputs is to be described is not a black-and-white issue. It is a trade-off between competing virtues. I agree that clear description of the inputs producing defined results and what those results should be <sup><b>a</b></sup> is a virtue. Another virtue is brevity, one valued by busy and productive programmers. A less obvious virtue is time not taken by the dev team for documentation, leaving them more time to improve the library. Personally, I am not so sure of the optimal trade that I would proclaim that it is made wrongly. > ... maybe the best improvement would be to remove the following sentence: "If sqlite3_malloc() fails during the processing of either routine (for example during a conversion from UTF-8 to UTF-16) then a NULL pointer is returned." I heartily disagree. That sentence informs API users who provide sensible inputs that they may get a NULL return, and when. This is a core concern, to be contrasted with what may be expected from nonsensical inputs. > One could also consider altering the start of the first sentence from "These routines return [...]" to "If successful, these routines return", but based on the responses in this thread, I assume the current wording is preferred. Your suggested wording is implicit (obviously IMO) in what is said now. In fact, your qualifier could be attached accurately to virtually every API in the library. If I were forced (under dire threat) to put that in the docs, it would go in a general "Caveats" section rather than cluttering the rest. On what is preferred: That is up for discussion. It is practically tautological that the present wording was preferred by its author when written. Those preferences change, with time, authors and feedback. I have seen many small doc improvements result from forum questions and comments. ---- <b>a.</b> "Should be" absent an implementation flaw.