Re: omission in lua_yield docs

[Patrick Rapin <toupie300@...>]

I also find odd the way lua_yieldk is described in the documentation.
>From experiments, I already knew that lua_yieldk in Lua 5.2 behaves
quite differently (by doing a longjmp) from lua_yield in Lua 5.1
(which returns -1).
It was a surprise to me when someone pointed that lua_yieldk should
only be called after a `return` statement.
What is the reason, since the function never returns ?

It may be as a little "backward usage compatibility" from Lua 5.1.
It may be for the same reasons why "return lua_error(L)" is also
widely used [1].
Nevertheless, at least it is clear in that case that this function
never returns:
  From lua_error documentation: "This function does a long jump, and
therefore never returns"
  Similarly from luaL_error : "This function never returns, but it is
an idiom to use it in C functions as return luaL_error(args)"

So why not explicitly state that lua_yieldk also never returns ? Is it
an implementation detail ?

[1] See the thread http://lua-users.org/lists/lua-l/2012-04/msg00737.html