From de1a2b11bab02196962810ef90b637cb9016e317 Mon Sep 17 00:00:00 2001
From: steve donovan <steve.j.donovan@gmail.com>
Date: Sun, 17 Apr 2011 19:01:57 +0200
Subject: [PATCH] table fields and their descriptions can be extracted from Lua
 table definitions

---
 ldoc.lua                | 29 ++++++++++++++++++++++-------
 lexer.lua               | 10 +++++++++-
 tests/simple/tables.lua | 17 +++++++++++++++++
 tools.lua               |  4 ++--
 4 files changed, 50 insertions(+), 10 deletions(-)
 create mode 100644 tests/simple/tables.lua

diff --git a/ldoc.lua b/ldoc.lua
index 5e31437..94e2ea2 100644
--- a/ldoc.lua
+++ b/ldoc.lua
@@ -186,9 +186,13 @@ function Lang:search_for_token (tok,type,value,t,v)
     return t ~= nil,t,v
 end
 
-function Lang:parse_function_header (tok,toks)
+function Lang:parse_function_header (tags,tok,toks)
 end
 
+function Lang:parse_extra (tags,tok,toks)
+end
+
+
 class.Lua(Lang)
 
 function Lua:_init()
@@ -227,10 +231,20 @@ function Lua:function_follows(t,v)
     return t == 'keyword' and v == 'function'
 end
 
-function Lua:parse_function_header (tok,toks)
-    local name = tools.get_fun_name(tok)
-    local formal_args = tools.get_parameters(toks)
-    return name,formal_args
+function Lua:parse_function_header (tags,tok,toks)
+    tags.name = tools.get_fun_name(tok)
+    tags.formal_args = tools.get_parameters(toks)
+    tags.class = 'function'
+end
+
+function Lua:parse_extra (tags,tok,toks)
+    if tags.class == 'table' and not tags.fields then
+        local res,t,v = self:search_for_token(tok,'{','{',tok())
+        if not res then return nil,t,v end
+        tags.formal_args = tools.get_parameters(toks,'}',function(s)
+            return s == ',' or s == ';'
+        end)
+    end
 end
 
 
@@ -353,8 +367,9 @@ local function parse_file(fname,lang)
             -- end of a block of document comments
             if ldoc_comment and tags then
                 if fun_follows then -- parse the function definition
-                    tags.name, tags.formal_args = lang:parse_function_header(tok,toks)
-                    tags.class = 'function'
+                    lang:parse_function_header(tags,tok,toks)
+                else
+                    lang:parse_extra(tags,tok,toks)
                 end
                 if tags.name then
                     F:new_item(tags,lineno()).inferred = fun_follows
diff --git a/lexer.lua b/lexer.lua
index 56a30c0..3b680c3 100644
--- a/lexer.lua
+++ b/lexer.lua
@@ -400,6 +400,14 @@ function lexer.get_separated_list(tok,endtoken,delim)
             return t == endtoken
         end
     end
+    local is_delim
+    if type(delim) == 'function' then
+        is_delim = delim
+    else
+        is_delim = function(t)
+            return t == delim
+        end
+    end
     local token,value
     while true do
         token,value=tok()
@@ -418,7 +426,7 @@ function lexer.get_separated_list(tok,endtoken,delim)
             else
                 tappend(tl,')')
             end
-        elseif token == delim and level == 1 then
+        elseif level == 1 and is_delim(token) then
             append(parm_values,tl) -- a new parm
             tl = {}
         else
diff --git a/tests/simple/tables.lua b/tests/simple/tables.lua
new file mode 100644
index 0000000..5e85ae1
--- /dev/null
+++ b/tests/simple/tables.lua
@@ -0,0 +1,17 @@
+------------
+-- A module containing tables.
+-- Shows how Lua table definitions can be conveniently parsed.
+-- @alias M
+
+local tables = {}
+local M = tables
+
+--- first table
+-- @table one
+M.one = {
+    A = 1, -- alpha
+    B = 2; -- beta
+}
+
+return M
+
diff --git a/tools.lua b/tools.lua
index 5cfece4..386658d 100644
--- a/tools.lua
+++ b/tools.lua
@@ -199,10 +199,10 @@ local function value_of (tok) return tok[2] end
 -- following the arguments. ldoc will use these in addition to explicit
 -- param tags.
 
-function M.get_parameters (tok)
+function M.get_parameters (tok,endtoken,delim)
     local args = List()
     args.comments = {}
-    local ltl = lexer.get_separated_list(tok)
+    local ltl = lexer.get_separated_list(tok,endtoken,delim)
 
     if #ltl[1] == 0 then return args end -- no arguments