I was looking into LDoc or LuaDoc to document my code. I saw from some examples (I have a clickable script that is pretty awesome to set my standards) that people already use some of these standards for documentation.
Since the boilerplate code for all game object scripts comes with predefined functions and a useful reference to instances thanks to self, most of my functions contain self as a parameter, and I will generally define some variables for self in the init function, i.e
function my_function(self)
self.myVar = nil
end
I’m not sure what’s the best way to document these instance variables.
btw, can I change the declaration of these functions to be local? I haven’t really tested/understood this.
Also, for lua best practices, if someone has good links, I am developing a project with a few friends and most of us are not experts in lua. I’ve been playing with defold for a couple of months now, but still I feel like a noob.
We use LDoc at King and it works well to generate documentation for our shared libs.
Which functions are you referring to? The lifecycle functions (init, final, update, on_message, on_input and on_reload) cannot be made local, but the functions you are declaring yourself can and should be declared local.
Well, LDoc has the @field annotation that you can use, but it also tries to infer table documentation. Check the manual and scroll down to “Table and Constant values”. The explicit form would be:
--- a useful table of constants
-- @field alpha first correction
-- @field beta second correction
-- @field gamma fudge factor
-- @table constants
While the inferred form would be:
--- a useful table of constants
M.constants = {
alpha = 0.23, -- first correction
beta = 0.443, -- second correction
gamma = 0.01 -- fudge factor
}