Steve Donovan's ldoc: recognized function declaration formats and possible bug

[Lorenzo Donati <lorenzodonatibz@...>]

Hi all and Steve in particular!

I don't know if this would be better handled by private mail. If it 
would, please tell me and sorry for the noise in advance.

In a recent thread Steve mentioned his ldoc documentation tool. I gave 
it a try (even if still pre-beta) since I find it very interesting. 
Especially because I try luadoc, but its prerequistes didn't suit me: it 
depends on LuaLogging which (IIRC) in turn required LuaRocks, and this 
latter is a big "no no" for me (I need and want to have full control on 
the sw installation on my system).

So the pure Lua, self-contained approach of ldoc suits me best.

Let's get to the point, now.

It seems that ldoc cannot automatically infer the following styles of 
function declarations inside a (new-style) module:

-- style 1
local function M_MyFunc(x)
  ...
end
M.MyFunc = M_MyFunc


-- style 2
local M_MyFunc
do
  local FUNC_PRIVATE_DATA = {}
  ...
  M_MyFunc = function(x)
   ...
   -- FUNC_PRIVATE_DATA used here inside
   ...
  end
end
M.MyFunc = M_MyFunc


This latter style is a bit weird, (I admit I'm a bit paranoid in keeping 
the scope of variables as short as possible :-), so maybe it is where 
@function tag belongs, but the first style is rather standard (IIRC it 
is also suggested somewhere in the WIKI), so probably it should be 
supported (even using @alias doesn't help).


I worked around the problem using the @function tag, but in this case it 
seems that the parser has some problems with long comments preceding the 
doc comments.

See the attached test file.


Thank you very much for the good job Steve!

Cheers.
-- Lorenzo





--- Test module
-- @alias M

--[===[ this works ]===]
--- Blah blah blah.
-- More blah
-- @function MyFunc1
-- @param x
local MyFunc1( x )
end

--[===[ this works  (blank line after this comment) ]===]

--- Blah blah blah.
-- More blah
-- @function MyFunc2
-- @param x
local MyFunc2( x )
end


--[===[ This still works with "weird" func declarations ]===]

--- Blah blah blah.
-- More blah
-- @function MyFunc3
-- @param x
local function M_MyFunc3(x)
  -- ...
end
M.MyFunc3 = M_MyFunc3

--[===[ But it stops working when the blank line is removed! ]===]
--- Blah blah blah.
-- More blah
-- @function MyFunc4
-- @param x
local function M_MyFunc4(x)
  -- ...
end
M.MyFunc4 = M_MyFunc4

--[===[ It works again when the long comment
spans several lines
]===]
--- Blah blah blah.
-- More blah
-- @function MyFunc5
-- @param x
local function M_MyFunc5(x)
  -- ...
end
M.MyFunc5 = M_MyFunc5