Page 1 of 1
LDoc: How do you do variations of functions
Posted: Fri Mar 25, 2016 2:47 am
by 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
Re: LDoc: How do you do variations of functions
Posted: Fri Mar 25, 2016 6:15 am
by 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.
Re: LDoc: How do you do variations of functions
Posted: Fri Mar 25, 2016 2:01 pm
by 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.
Re: LDoc: How do you do variations of functions
Posted: Fri Mar 25, 2016 3:29 pm
by s-ol
You can mark parameters as optional using -- @param[opt] name. But that won't allow completely different signatures still.
Re: LDoc: How do you do variations of functions
Posted: Fri Mar 25, 2016 7:55 pm
by airstruck
davisdude wrote: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?
davisdude wrote: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.
Re: LDoc: How do you do variations of functions
Posted: Fri Mar 25, 2016 9:01 pm
by 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.
Re: LDoc: How do you do variations of functions
Posted: Fri Mar 25, 2016 10:02 pm
by 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