LuaDoc and Automatically Generated Functions

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

LuaDoc and Automatically Generated Functions

Ken Smith-2
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?

Reply | Threaded
Open this post in threaded view
|

Re: LuaDoc and Automatically Generated Functions

Tomás Guisasola-2
	Hi Ken

> 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?
	LuaDoc was developed when there were no anonymous functions
in Lua and even at that time the job wasn't easy.  I am not sure about
what would be the best way to document the case you mention, but I have
the same problem and I do something like:

---------------------------------------------------------------------
-- Cria uma ligação entre um usuário e um centro.
-- @class function
-- @name liga_usuario_centro
-- @param db Objeto conexão.
-- @param user Número com o identificador do usuário.
-- @param centro Identificador OU código do centro.
--  (neste caso, o identificador é obtido por um sub-select).
-- @return Número de linhas inseridas.
-- @return Número com o identificador do centro.

liga_usuario_centro = G_liga_usuario"centro"

	Where G_liga_usuario is a "generator" function.

> I've filed a few bugs against LuaDoc 3.0 on LuaForge.  Is anyone
> babysitting this project?
	Yes, I noticed.  I am a little busy now but will take a look
at those bugs...

> Is this the defacto standard way to
> document Lua code or are there alternatives?
	I think there is no "defacto" as is usual with Lua :-)

	Thanks,
		Tomás


Reply | Threaded
Open this post in threaded view
|

Re: LuaDoc and Automatically Generated Functions

RJP Computing
On Jan 25, 2008 1:35 PM, Tomas Guisasola Gorham <[hidden email]> wrote:
       LuaDoc was developed when there were no anonymous functions
in Lua and even at that time the job wasn't easy.  I am not sure about
what would be the best way to document the case you mention, but I have
the same problem and I do something like:

---------------------------------------------------------------------
-- Cria uma ligação entre um usuário e um centro.
-- @class function
-- @name liga_usuario_centro
-- @param db Objeto conexão.
-- @param user Número com o identificador do usuário.
-- @param centro Identificador OU código do centro.
--  (neste caso, o identificador é obtido por um sub-select).
-- @return Número de linhas inseridas.
-- @return Número com o identificador do centro.

liga_usuario_centro = G_liga_usuario"centro"

       Where G_liga_usuario is a "generator" function.

Is there a way to document function overloading? When I have two functions of the same name, but different parameters LuaDoc just takes the last one it incounters. Is there a way around this?
--
Regards,
Ryan
Reply | Threaded
Open this post in threaded view
|

Re: LuaDoc and Automatically Generated Functions

Luís Eduardo Jason Santos-2
In reply to this post by Ken Smith-2
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 <[hidden email]> 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