lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]


First of all, thanks for your interest in LuaDoc.

The LuaDoc project has received little attention lately, and is due to a considerable refactoring in the near future, to benefit from the excellent LEG project.

Once our plunge into LEG is done, it's going to be much easier to represent complex code structures in generated documentation.

As Tomas is kinda busy right now, I am making the preliminary experiments into what can be a 4.0 version of LuaDoc - thou I don't think you can expect any usable results in the next few weeks.

Any help is welcome.

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?



--
Luís Eduardo Jason Santos