Documenting my code

Questions
#1

Hi there,

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.

thanks

#2

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.

I like this style guide: https://github.com/Olivine-Labs/lua-style-guide
Some performance tips: https://www.lua.org/gems/sample.pdf

2 Likes
#3

Thanks for the pointers!
How would you document “self” with LDoc?
what I mean is how to document instance properties.

And do you have a preference for unit tests?
I found this page http://lua-users.org/wiki/UnitTesting

#4

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
}

At King we use our own unit testing framework, but for my own stuff I’ve used Telescope. I even made a forum post about unit testing and I created a repo with Telescope and some additional wrapper code to simplify testing of async stuff.