On Jan 25, 2008 3:32 PM, Ken Smith <
kgsmith@gmail.com> wrote:
I have been using LuaDoc 3.0 and find it fairly natural for the most
part. I've recently run into a conundrum with respect to documenting
automatically generated functions. Consider the following.
% cat<<EOF>test.lua
local units = {
meters = {--[[...]]},
seconds = {--[[...]]},
--[[...]]
}
for name,_ in pairs(units) do
---@description Automatically generated function.
--@name name
--@class function
--@param x number
--@return number
_G[name] = function(x)
return x*2
end
end
print('meters(5) = ' .. tostring(meters(5)))
print('seconds(5) = ' .. tostring(seconds(5)))
EOF
Clearly, my attempt to put the documentation in the loop is
meaningless for LuaDoc but it demonstrates what I yearn to do. I want
to automatically generate simple boilerplate documentation for each
function. Just something that will put it in the LuaDoc output so end
users know these functions exist. The documentation can be uniform
because, at least in this case, their usage and effect will be
obvious. I suppose I can do it like this, but it leaves a bad taste
in my mouth.
% cat<<EOF>test2.lua
local units = {
meters = {--[[...]]},
seconds = {--[[...]]},
--[[...]]
}
for name,_ in pairs(units) do
_G[name] = function(x)
return x*2
end
end
---@description Automatically generated function.
--@name meters
--@class function
--@param x number
--@return number
---@description Automatically generated function.
--@name seconds
--@class function
--@param x number
--@return number
print('meters(5) = ' .. tostring(meters(5)))
print('seconds(5) = ' .. tostring(seconds(5)))
EOF
In a way, this problem is a credit to Lua. The Doxygen style of
documenting that LuaDoc adopts simply doesn't work as well when the
code doesn't sit still and behave :) Any ideas on how I can document
automatically generated entities in LuaDoc?
Ken Smith
ps.
I've filed a few bugs against LuaDoc 3.0 on LuaForge. Is anyone
babysitting this project? Is this the defacto standard way to
document Lua code or are there alternatives?
