Documenting Lua code?

Code is as much an exercise in communicating with humans as it is with computers: as Donald Knuth says "Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do". (After a few months, you are that human being that needs an explanation.)

LuaDoc is most commonly used. The style is similar to other documentation generation tools such as JavaDoc:

--- Three dashes mark the start; this sentence is the short summary.
-- You can add more lines here;
-- Note that they can contain HTML, and in fact you need an explicit <br>
-- to break lines.
-- @param first first name of person (string)
-- @param second second name of person (string)
-- @param age years; (optional number)
-- @return an object (Person)
-- @usage person = register_person('john','doe')
-- @see Person function register_person(first,second,age)
...
end

It is useful to comment your code in a structured way like this anyway, since Lua does not indicate the type of function arguments. If a user has to guess what to pass to a function by having to read the code then the function is not well documented. Having a convention for the type of the arguments is also useful.

However, auto-generated documentation is rarely enough. A set of well-documented tests does double duty in this respect.