LDoc: How do you do variations of functions

[davisdude]

I'm going through fixing up an old project of mine and adding LDoc to it. However, one of the functions works like this:

Code: Select all

function foo( ... )
    args = { ... }
    if #args == 1 then
        bar()
    elseif #args == 2 then
        baz()
    else
        bam()
    end
end

How would I document this with LDoc? Thanks

[airstruck]

Can you post the actual function here, trimmed down to relevant stuff if necessary? You're probably not going to find a satisfying way to document varargs that aren't just a sequence of the same kind of arg, you might have to write the args list differently in order to document it in a meaningful way.

Take a look at the four.lua example, though. Ldoc will let you document any number of extra args at the end in a variadic function, it's just not as nice as having actual args to document.

[davisdude]

I might have oversimplified too much, but here's what I have right now:

Code: Select all

--- Get the slope of a line
-- @function line.getSlope
-- @tparam number x1 The x-coordinate of the first point
-- @tparam number y1 The y-coordinate of the first point
-- @tparam number x2 The x-coordinate of the second point
-- @tparam number y2 The y-coordinate of the second point
-- @treturn[1] number The slope of the line
-- @treturn[2] boolean `nil` if the line is vertical

--- Get the slope of a line
-- @function line.getSlope
-- @tparam table p1 The coordinates in the form `{ x1, y1 }`
-- @tparam table p1 The coordinates in the form `{ x2, y2 }`
function line.getSlope( ... )
	local args = varargs( ... )
	local m
	if #args == 4 then
		m = ( args[2] - args[4] ) / ( args[1] - args[3] )
	elseif #args == 2 then
		m = ( args[1][2] - args[2][2] ) / ( args[1][1] - args[2][1] )
	end
	return m
end

This isn't really ideal since it create two references to the function, but it's the best I could think of.

[s-ol]

You can mark parameters as optional using -- @param[opt] name. But that won't allow completely different signatures still.

[airstruck]

here's what I have right now

Ah, I see what you mean. Does that actually work, or does Ldoc complain about that symbol being redefined?

This isn't really ideal since it create two references to the function, but it's the best I could think of.

Well, it seems like you're more or less emulating function overloading. If you were documenting a polymorphic function in a language like C++, you'd end up with pretty much the same thing, wouldn't you? If Ldoc will let you write it like your example and can display it in a sane way, that's probably the best you can hope for.

[davisdude]

Yeah, it does work, but you can only link to the top variation of the function. It's not ideal, but it does work.

[airstruck]

You might try using a custom template to fix presentation issues if that's the only problem. Should just be a small modification to the default template.

What about something like this instead?

Code: Select all

--[[--
Get the slope of a line from components.

@tparam number x1 The x-coordinate of the first point
@tparam number y1 The y-coordinate of the first point
@tparam number x2 The x-coordinate of the second point
@tparam number y2 The y-coordinate of the second point

@treturn number|nil The slope of the line, or nil if vertical.
--]]--
function line.getSlopeFromComponents (x1, y1, x2, y2)
    return (y1 - y2) / (x1 - x2)
end

--[[--
Get the slope of a line from points.

@tparam table p1 The coordinates in the form `{ x1, y1 }`
@tparam table p2 The coordinates in the form `{ x1, y1 }`

@treturn number|nil The slope of the line, or nil if vertical.
--]]--
function line.getSlopeFromPoints (p1, p2)
    return line.getSlopeFromComponents(p1[1], p1[2], p2[1], p2[2])
end

--[[--
Get the slope of a line.

Calls `getSlopeFromComponents` or `getSlopeFromPoints` based on
the number of arguments.

@treturn number|nil The slope of the line, or nil if vertical.
--]]--
function line.getSlope (...)
    if select('#', ...) < 4 then
        return line.getSlopeFromPoints(...)
    end
    return line.getSlopeFromComponents(...)
end