composite return types experiment

ldoc-scm-2.rockspec

@@ -0,0 +1,60 @@
+package = "ldoc"
+version = "scm-2"
+
+source = {
+  dir="LDoc",
+  url = "git://github.com/stevedonovan/LDoc.git"
+}
+
+description = {
+  summary = "A Lua Documentation Tool",
+  detailed = [[
+   LDoc is a LuaDoc-compatible documentation generator which can also
+   process C extension source. Markdown may be optionally used to
+   render comments, as well as integrated readme documentation and
+   pretty-printed example files
+  ]],
+  homepage='http://stevedonovan.github.com/ldoc',
+  maintainer='steve.j.donovan@gmail.com',
+  license = "MIT/X11",
+}
+
+dependencies = {
+  "penlight","markdown"
+}
+
+build = {
+  type = "builtin",
+  modules = {
+    ["ldoc.tools"] = "ldoc/tools.lua",
+    ["ldoc.lang"] = "ldoc/lang.lua",
+    ["ldoc.parse"] = "ldoc/parse.lua",
+    ["ldoc.html"] = "ldoc/html.lua",
+    ["ldoc.lexer"] = "ldoc/lexer.lua",
+    ["ldoc.markup"] = "ldoc/markup.lua",
+    ["ldoc.prettify"] = "ldoc/prettify.lua",
+    ["ldoc.doc"] = "ldoc/doc.lua",
+    ["ldoc.html.ldoc_css"] = "ldoc/html/ldoc_css.lua",
+    ["ldoc.html.ldoc_ltp"] = "ldoc/html/ldoc_ltp.lua",
+    ["ldoc.html.ldoc_one_css"] = "ldoc/html/ldoc_one_css.lua",
+    ["ldoc.builtin.globals"] = "ldoc/builtin/globals.lua",
+    ["ldoc.builtin.coroutine"] = "ldoc/builtin/coroutine.lua",
+    ["ldoc.builtin.global"] = "ldoc/builtin/global.lua",
+    ["ldoc.builtin.debug"] = "ldoc/builtin/debug.lua",
+    ["ldoc.builtin.io"] = "ldoc/builtin/io.lua",
+    ["ldoc.builtin.lfs"] = "ldoc/builtin/lfs.lua",
+    ["ldoc.builtin.lpeg"] = "ldoc/builtin/lpeg.lua",
+    ["ldoc.builtin.math"] = "ldoc/builtin/math.lua",
+    ["ldoc.builtin.os"] = "ldoc/builtin/os.lua",
+    ["ldoc.builtin.package"] = "ldoc/builtin/package.lua",
+    ["ldoc.builtin.string"] = "ldoc/builtin/string.lua",
+    ["ldoc.builtin.table"] = "ldoc/builtin/table.lua",
+  },
+  copy_directories = {'doc','tests'},
+  install = {
+    bin = {
+      ldoc = "ldoc.lua"
+    }
+  }
+}
+

ldoc/doc.lua

@@ -778,6 +778,7 @@ function Item:type_of_ret(idx)
 end
 
 local function integer_keys(t)
+   if not t then return 0 end
    for k in pairs(t) do
       local num = tonumber(k)
       if num then return num end
@@ -785,8 +786,14 @@ local function integer_keys(t)
    return 0
 end
 
+function Item:return_type(r)
+   if not r.type then return '' end
+   return r.type, r.ctypes
+end
+
 function Item:build_return_groups()
-   local retmod = self.modifiers['return']
+   local modifiers = self.modifiers
+   local retmod = modifiers['return']
    local groups = List()
    local lastg, group
    for i,ret in ipairs(self.ret) do
@@ -797,9 +804,29 @@ function Item:build_return_groups()
          groups:append(group)
          lastg = g
       end
-      group:append({text=ret, type = mods.type or ''})
+      group:append({text=ret, type = mods.type or '',mods = mods})
    end
    self.retgroups = groups
+   -- cool, now see if there are any treturns that have tfields to associate with
+   local fields = self.tags.field
+   if fields then
+      local fcomments = List()
+      for i,f in ipairs(fields) do
+         local name, comment = f:match('%s*([%w_%.:]+)(.*)')
+         fields[i] = name
+         fcomments[i] = coment
+      end
+      local fmods = modifiers.field
+      for group in groups:iter() do for r in group:iter() do
+         if r.mods and r.mods.type  == '*'  then
+            local ctypes = List()
+            for i,f in  ipairs(fields) do
+               ctypes:append {name=f,type=fmods[i].type,comment=fcomments[i]}
+            end
+            r.ctypes = ctypes
+         end
+      end end
+   end
 end
 
 function Item:subparam(p)

ldoc/html/ldoc_ltp.lua

@@ -187,12 +187,21 @@ return [==[
     <h3>Returns:</h3>
 #   for i,group in ldoc.ipairs(groups) do local li,il = use_li(group)
     <ol>
-#   for r in group:iter() do
+#   for r in group:iter() do local type, ctypes = item:return_type(r)
         $(li)
-#      local tp = ldoc.typename(r.type);   if tp ~= '' then
-          <span class="types">$(tp)</span>
-#      end
+#      if type ~= '' then
+           <span class="types">$(ldoc.typename(type))</span>
+#     end
         $(M(r.text,item))$(il)
+#    if ctypes then
+      <ul>
+#    for c in ctypes:iter() do
+            <li><span class="parameter">$(c.name)</span>
+            <span class="types">$(ldoc.typename(c.type))</span>
+            $(M(c.comment,item))</li>
+#     end
+        </ul>
+#    end -- if ctypes
 #     end -- for r
     </ol>
 #   if i < #groups then

tests/styles/priority_queue.lua

@@ -1,7 +1,10 @@
 --------------------------------------------------------------------------------
---- Queue of objects sorted by priority
+--- Queue of objects sorted by priority.
 -- @module lua-nucleo.priority_queue
--- This file is a part of lua-nucleo library
+-- This file is a part of lua-nucleo library. Note that if you wish to spread
+-- the description after tags, then invoke with `not_luadoc=true`. 
+-- The flags here are `ldoc -X -f backtick priority_queue.lua`, which
+-- also expands backticks.
 -- @copyright lua-nucleo authors (see file `COPYRIGHT` for the license)
 --------------------------------------------------------------------------------
 
@@ -34,7 +37,7 @@ do
 
   local insert = function(self, priority, value)
     method_arguments(
-        self,
+        s
         "number", priority
       )
     assert(value ~= nil, "value can't be nil") -- value may be of any type, except nil

tests/styles/struct.lua

@@ -0,0 +1,12 @@
+------
+-- functions returning compound types
+-- @module struct
+
+-----
+-- returns a 'struct'.
+-- @string name your name dammit
+-- @treturn * details of person
+-- @tfield string name of person
+-- @tfield int age of person
+function struct(name) end
+