> All this sounds like an attempt at sounding inexperienced and naive.
Fact is, the code that I posted earlier, wherein lua_next is replaced by lua_gettable, raises a Lua error, as would be expected given its 'e' error category. Yet the original code crashes, despite lua_next's identical error category. Just given the documentation, the radical difference is not obvious at all. Once you learn the difference the hard way, you can discern subtle cues in the language that might mean that. It would be far more appropriate if the lua_next clause said something like this: "N.B.: The value at the given index MUST be a table; otherwise the behaviour is undefined (in the C-language sense, e.g., a crash)."
> In general, the documentation of the C API assumes a higher level of nous from the reader than that of the Lua language.
I am not a native speaker and the use of "nous" is not very familiar to me, so I am not completely sure what you meant. In my opinion, Lua's very compact API and its simplicity is a major ingredient in Lua's success. It is not perceived as a difficult or dangerous thing to use, and it is usually indeed not. The Lua stack interface is a feature unique to Lua, unfamiliar to programmers even with some solid C background. In many cases, like lua_tonumber(), it is safe to call the API even if the stack does not contain an appropriate type at the specified index. So this creates a peace of mind, where "Lua just does the right thing even when the type is wrong". In a rather small number of cases, it is not safe to call the API unless the stack contains a particular type at the specified index, and this is not stressed, as far as I can tell, anywhere in the documentation, let alone in the clauses on those particular functions. This knowledge is arcane and comes naturally only from having made the mistake with a particular function, which will not necessarily prevent from making the mistake with another function. If you mean that this is the right way to acquire the knowledge, then I disagree.
Because, as I said above, the number of functions requiring a very strict stack discipline (stricter than the valid/acceptable index requirement) is not large, I think it would be good to document that explicitly. Even if that does not prevent making those mistakes, it will be much easier to understand that it is indeed a mistake and require no research as to whether this is a mistaken use of the API or a bug in Lua.
