How to handle function variants

[rm-code]

Some functions have multiple variants like love.graphics.push. These variants sometimes have their descriptions on the wiki. The question is how to handle these in the documentation.

My suggestion would be this:

{
    name = 'push',
    description = 'Copies and pushes the current coordinate transformation to the transformation stack.\n\nThis function is always used to prepare for a corresponding pop operation later. It stores the current coordinate transformation state into the transformation stack and keeps it active. Later changes to the transformation can be undone by using the pop operation, which returns the coordinate transform to the state it was in before calling push.',
    functions = {
        {
            description = 'Pushes the current transformation to the transformation stack.',
        },
        { 
            description = 'Pushes a specific type of state to the stack.',
            arguments = {
                {
                    type = 'StackType',
                    name = 'stack',
                    description = 'The type of stack to push (e.g. just transformation state, or all love.graphics state).'
                },
            }
        }
    }
},

[zorggn]

I think your solution's good, since it's most straightforward, even with the possible duplication of a few keys and/or values per variant.

[pablomayobre]

That could even account for the Notes too, for example Thread:start has a note at the bottom of the variant that supports arguments that says "Note: The arguments passed to Thread:start are accessible in the Thread through the vararg (...) variable.". This could easily fit in the description

[leafi]

Am I right in thinking this is how the code works right now? It seems pretty reasonable - though a bit strange having 'functions' inside 'functions' - and it makes sense.

[rm-code]

Maybe it would be a good idea to document the table structure, so people can use the doc without having to dig through the code.

[pablomayobre]

Yeah, that would be nice indeed. Also I think the variants descriptions would be nice to have

[rm-code]

@leafi I didn't quite get your comment until now. I agree that having a functions table inside of "functions" is a bit misleading.

This is how it currently looks:

-- Functions
functions = {
    { -- Function 1
        name = 'Name of the function',
        description = 'The description of what the function does',
        functions = {
            arguments = { -- (optional)
                { -- Argument 1
                    type = 'The variable type',
                    name = 'The variable name',
                    description = 'The description of the variable.'
                },
                { -- Argument 2
                    type = '...',
                    name = '...',
                    description = '...',
                },
            },
            returns = { -- (optional)
                { -- Return statement 1
                    type = 'The returned variable type',
                    name = 'The variable name',
                    description = 'The description of the variable.'
                },
                { -- Return statement 2
                    type = '...',
                    name = '...',
                    description = '...'
                },
            }
        },
    },
    {
    -- Function 2
    -- ...
    },
}

This is how it should look IMO:

-- Functions
functions = {
    { -- Function 1
        name = 'Name of the function',
        description = 'The description of what the function does',
        variants = {
            {
                description = 'The description detailing what this variant does',
                arguments = { -- (optional)
                    { -- Argument 1
                        type = 'The variable type',
                        name = 'The variable name',
                        description = 'The description of the variable.'
                    },
                    { -- Argument 2
                        type = '...',
                        name = '...',
                        description = '...',
                    },
                },
                returns = { -- (optional)
                    { -- Return statement 1
                        type = 'The returned variable type',
                        name = 'The variable name',
                        description = 'The description of the variable.'
                    },
                    { -- Return statement 2
                        type = '...',
                        name = '...',
                        description = '...'
                    },
                }
            },
        },
    },
    {
    -- Function 2
    -- ...
    },
}

Needless to say this would require quite a lot of changes 😄

[leafi]

Yeah, having 'variants' instead would be nice. Rewriting all the files probably would be best done with a script rather than by hand.

...With some difficulty, I think I've managed to write that script.
It works based on assumptions about indentation before 'functions' lines, erroring out if the lines don't match our expectations, and at the very end also loading love_api as Lua and verifying the results are correct that way.

It runs in-place and overwrites existing Lua files. (So you can't run it twice. Fun!)

https://gist.github.com/leafi/9cac45df526be3625e8a

It's a bit hairy, so it's fair enough if you don't want to use it...

(Edit: Gist updated to check that no modules or types have gained .variants fields.)
(Edit 2: Forgot about love_api.lua's callbacks... Fixed.)

[rm-code]

@leafi The script looks good - I didn't have the time yet to try it out myself. If you want to, you can fork and create a pull request and I'll merge it later if the changes are okay.

[leafi]

@rm-code I'll do that, then.