return groups; experimental 'error' tag

ldoc.lua

@@ -149,6 +149,18 @@ function ldoc.tparam_alias (name,type)
    ldoc.alias(name,{'param',modifiers={type=type}})
 end
 
+ldoc.alias ('error',function(tags,value,modifiers)
+    local t = List{'nil','error message'}
+    local oret = tags['return']
+    if not oret or type(oret) == 'string' then
+        if oret then t:insert(1,oret) end
+        tags:add('return',t)
+    else
+        tags['return']:extend(t)
+    end
+end)
+
+
 ldoc.tparam_alias 'string'
 ldoc.tparam_alias 'number'
 ldoc.tparam_alias 'int'

ldoc/doc.lua

@@ -405,10 +405,7 @@ function Item:_init(tags,file,line)
    self.tags = {}
    self.formal_args = tags.formal_args
    tags.formal_args = nil
-   local iter = tags.iter
-   if not iter then
-      iter = Map.iter
-   end
+   local iter = tags.iter or Map.Iter
    for tag in iter(tags) do
       self:set_tag(tag,tags[tag])
    end
@@ -482,7 +479,7 @@ function Item.check_tag(tags,tag, value, modifiers)
    if alias then
       if type(alias) == 'string' then
          tag = alias
-      else
+      elseif type(alias) == 'table' then --{ tag, value=, modifiers = }
          local avalue,amod
          tag, avalue, amod = alias[1],alias.value,alias.modifiers
          if avalue then value = avalue..' '..value end
@@ -496,6 +493,8 @@ function Item.check_tag(tags,tag, value, modifiers)
                modifiers[m] = v
             end
          end
+      else -- has to be a function
+         alias(tags,value,modifiers)
       end
    end
    local ttype = known_tags[tag]
@@ -684,6 +683,9 @@ function Item:finish()
       self.params = params
       self.args = build_arg_list (names,pmods)
    end
+   if self.ret then
+      self:build_return_groups()
+   end
 end
 
 -- ldoc allows comments in the formal arg list to be used, if they aren't specified with @param
@@ -776,6 +778,33 @@ function Item:type_of_ret(idx)
    return rparam and rparam.type or ''
 end
 
+local function integer_keys(t)
+   for k in pairs(t) do
+      local num = tonumber(k)
+      if num then return num end
+   end
+   return 0
+end
+
+function Item:build_return_groups()
+   local retmod = self.modifiers['return']
+   local groups = List()
+   local lastg, group
+   for i,ret in ipairs(self.ret) do
+      local mods = retmod[i]
+      local g = integer_keys(mods)
+      print(g,lastg)
+      if g ~= lastg then
+         group = List()
+         groups:append(group)
+         lastg = g
+      end
+      group:append({text=ret, type = mods.type or ''})
+   end
+   print(groups)
+   self.retgroups = groups
+end
+
 function Item:subparam(p)
    local subp = rawget(self.subparams,p)
    if subp then
@@ -794,7 +823,6 @@ function Item:display_name_of(p)
    end
 end
 
-
 function Item:warning(msg)
    local file = self.file and self.file.filename
    if type(file) == 'table' then require 'pl.pretty'.dump(file); file = '?' end

ldoc/html/ldoc_ltp.lua

@@ -183,19 +183,22 @@ return [==[
     </ul>
 #   end -- if params
 
-#   if show_return and item.ret then
-#     local li,il = use_li(item.ret)
+#  if show_return and item.retgroups then local groups = item.retgroups
     <h3>Returns:</h3>
+#   for i,group in ldoc.ipairs(groups) do local li,il = use_li(group)
     <ol>
-#     for i,r in ldoc.ipairs(item.ret) do
+#   for r in group:iter() do
         $(li)
-#       local tp = ldoc.typename(item:type_of_ret(i))
-#       if tp ~= '' then
+#      local tp = ldoc.typename(r.type);   if tp ~= '' then
           <span class="types">$(tp)</span>
-#       end
-        $(M(r,item))$(il)
-#     end -- for
+#      end
+        $(M(r.text,item))$(il)
+#     end -- for r
     </ol>
+#   if i < #groups then
+     <h3>Or</h3>
+#   end
+#   end -- for group
 #   end -- if returns
 
 #   if show_return and item.raise then