Documenting the Lua interface

[martins]

I've been looking at LDoc, a documentation system for Lua that might make writing the reference manual for the Orbiter Lua interface a bit easier. The syntax is somewhat similar to doxygen, and it allows to document not just Lua script functions, but also the C++ source files containing the interface definitions.

There are a few quirks though: The system can't guess the name of the Lua function represented by the C code (it isn't smart enough to scan the table that associates the C function with the Lua function name), so you have to specify the Lua function name manually with a @function tag.

It also requires functions to be grouped into modules, but only allows one module tag per file. This makes sense for modules defined in Lua, but less so for modules defined in C via the luaL_openlib call, since you can have multiple modules defined in a single C source file. This means that I probably will have to break up interpreter.cpp into multiple files for a single module each, to make LDoc work.

 

[kuddel]

Whatever feels right for you :thumbup:
But still there's no "check" whether e.g. return-types or parameter signatures really match the documentation, right?
In that case, LDoc only helps in having the code and the documentation "close together"...which is a little bit better, but only a little

You didn't like to commit the Lua documentation html files[*]? Or is the Orbiter (Core) project structure just too much entangled?

[*]...with just the HTML files, any human editor must of course stick to the "style" guideline