I'm trying to improve LuaAPI documentation by using the information from ToLua++ when it generates the bindings. The parser knows more about each function than the runtime can query - the number and types of parameters and return values (including overloads) and whether it is static or not.
I believe I could even make it read the doxycomments and attach them to the functions, classes and enums. The problem is that that would require a change in the ToLua++ sources, which means more difficult maintenance, if a new ToLua++ version comes out. However, considering that it is working alright for us now and it hasn't been updated for years, I pretty much doubt that it would indeed need any updates at all, so this entire thing could be viable.
Another nice point that I managed to do already is that the bindings can be generated without the actual ToLua++ executable, the basic Lua interpreter is actually enough. This could simplify cross-compiling, because we could use system-provided Lua in such a case, and won't have to compile any native executable while cross-compiling. However, we shouldn't remove the ToLua++ executable completely, because it's much easier to use than "native" (read: missing) Lua on Windows.
Another thought that has crossed my mind was to actually get rid of the ToLua++ parser altogether, and instead define the API in the form of a description - something like the APIDesc plugin uses, extended with the parameter and return value information. Then a Lua script could be used to generate the bindings from that description.
On the positive side, we could make the script smarter than a C++ parser, so it could know for example about call chaining (cChatMessage:new():AddText():AddUrl():AddText()...), could implement static functions that can use either calling convention (cClass.StaticFn() or cClass:StaticFn()), it could use the cLuaState class, it could understand callbacks. At the very least, it wouldn't generate bogus return values, such as ToLua++ now does for all "const cClass &" parameters (int SomeFn(const AString & a_Text) currently generates a binding that has two return values, the int and the string).
On the negative side this would mean that each binding would need to be described in the description file, rather than adding a "// tolua_export" comment to a function.
Back to the positive side, this would mean that each new binding would be properly documented
Thoughts?
I believe I could even make it read the doxycomments and attach them to the functions, classes and enums. The problem is that that would require a change in the ToLua++ sources, which means more difficult maintenance, if a new ToLua++ version comes out. However, considering that it is working alright for us now and it hasn't been updated for years, I pretty much doubt that it would indeed need any updates at all, so this entire thing could be viable.
Another nice point that I managed to do already is that the bindings can be generated without the actual ToLua++ executable, the basic Lua interpreter is actually enough. This could simplify cross-compiling, because we could use system-provided Lua in such a case, and won't have to compile any native executable while cross-compiling. However, we shouldn't remove the ToLua++ executable completely, because it's much easier to use than "native" (read: missing) Lua on Windows.
Another thought that has crossed my mind was to actually get rid of the ToLua++ parser altogether, and instead define the API in the form of a description - something like the APIDesc plugin uses, extended with the parameter and return value information. Then a Lua script could be used to generate the bindings from that description.
On the positive side, we could make the script smarter than a C++ parser, so it could know for example about call chaining (cChatMessage:new():AddText():AddUrl():AddText()...), could implement static functions that can use either calling convention (cClass.StaticFn() or cClass:StaticFn()), it could use the cLuaState class, it could understand callbacks. At the very least, it wouldn't generate bogus return values, such as ToLua++ now does for all "const cClass &" parameters (int SomeFn(const AString & a_Text) currently generates a binding that has two return values, the int and the string).
On the negative side this would mean that each binding would need to be described in the description file, rather than adding a "// tolua_export" comment to a function.
Back to the positive side, this would mean that each new binding would be properly documented
Thoughts?