Problems with the documentation

[Ben Sizer <kylotan@...>]

I recently had a problem with Lua 5 where lua_register was silently
failing to actually register the function I provided (which I may ask
again about later), and in attempting to use the documentation to fix
the problem I discovered several flaws in it.

Lua 5 has the following: "To register a C function to Lua, there is
the following convenience macro: lua_register". Yet in the docs for
5.1, lua_register has disappeared, and the closest thing to it -
luaL_register - seems to do something significantly different. The
'Changes in the API' part of the documentation makes no reference to
the disappeared function, which is a shame because much of the
previous documentation and tutorials on Lua use 'lua_register'
extensively. It's quite drastic to remove a key part of the API
between minor versions, but doubly so to remove all traces of it from
the documentation!

It seems like the equivalent information in 5.1 is now in
'lua_pushcfunction', which has a very short and unhelpful description
that is written in terms of lua_pushcclosure. This is surely not an
intuitive way to think about binding C functions to Lua, since most C
programmers will probably have never used a closure before, if they
even know what one is. It is as if binding normal C functions is
considered so obvious that it doesn't require documentation, which I
can assure you is not the case. Why remove the 'Defining C Functions'
section from the manual?

This isn't the first time this has happened; in Lua 4 there was a
function called 'lua_dostring', but in Lua 5 the only reference to it
was "dostring is deprecated. Use loadstring instead." This didn't even
refer to the lua_dostring in the C API, which had disappeared.

So, I guess the purpose of this email was to bring this to somebody's
attention. The language seems to be getting better but I find it hard
to use when the API changes rapidly and the documentation does not
keep up.

--
Ben Sizer