ldoc.alias can specify a function which must return tag, value, modifiers like Item:check_tag. The alias error works with return groups

ldoc.lua

@@ -149,18 +149,12 @@ 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
+ldoc.alias ('error',function(tags,value)
+    local g = '2'
+    tags:add('return','',{[g]=true,type='nil'})
+    return 'return', value, {[g]=true,type='string'}
 end)
 
-
 ldoc.tparam_alias 'string'
 ldoc.tparam_alias 'number'
 ldoc.tparam_alias 'int'

ldoc/doc.lua

@@ -405,7 +405,7 @@ function Item:_init(tags,file,line)
    self.tags = {}
    self.formal_args = tags.formal_args
    tags.formal_args = nil
-   local iter = tags.iter or Map.Iter
+   local iter = tags.iter or Map.iter
    for tag in iter(tags) do
       self:set_tag(tag,tags[tag])
    end
@@ -494,7 +494,7 @@ function Item.check_tag(tags,tag, value, modifiers)
             end
          end
       else -- has to be a function
-         alias(tags,value,modifiers)
+         return alias(tags,value,modifiers)
       end
    end
    local ttype = known_tags[tag]
@@ -793,7 +793,6 @@ function Item:build_return_groups()
    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)
@@ -801,7 +800,6 @@ function Item:build_return_groups()
       end
       group:append({text=ret, type = mods.type or ''})
    end
-   print(groups)
    self.retgroups = groups
 end
 

ldoc/parse.lua

@@ -70,7 +70,8 @@ local function parse_colon_tags (text)
    return preamble,tag_items
 end
 
--- Tags are stored as an ordered map
+-- Tags are stored as an ordered multi map from strings to strings
+-- If the same key is used, then the value becomes a list
 local Tags = {}
 Tags.__index = Tags
 
@@ -89,9 +90,22 @@ function Tags.new (t,name)
    return tags
 end
 
-function Tags:add (tag,value)
+function Tags:add (tag,value,modifiers)
+   if modifiers then -- how modifiers are encoded
+      value = {value,modifiers=modifiers}
+   end
+   local ovalue = rawget(self,tag)
+   if ovalue then -- previous value?
+      if getmetatable(ovalue) ~= List then
+         ovalue = List{ovalue}
+      end
+      ovalue:append(value)
+      value = ovalue
+   end
    rawset(self,tag,value)
-   self._order:append(tag)
+   if not ovalue then
+      self._order:append(tag)
+   end
 end
 
 function Tags:iter ()
@@ -128,17 +142,8 @@ local function extract_tags (s,args)
       if not value:match '\n[^\n]+\n' then
          value = strip(value)
       end
-
-      if modifiers then value = { value, modifiers=modifiers } end
-      local old_value = tags[tag]
-
-      if not old_value then -- first element
-         tags:add(tag,value)
-      elseif type(old_value)=='table' and old_value.append then -- append to existing list
-         old_value :append (value)
-      else -- upgrade string->list
-         tags:add(tag,List{old_value, value})
-      end
+      
+      tags:add(tag,value,modifiers)
    end
    return tags --Map(tags)
 end

tests/styles/multiple.lua

@@ -0,0 +1,23 @@
+------
+-- Various ways of indicating errors
+-- @module multiple
+
+-----
+-- function with return groups.
+-- @treturn[1] string result
+-- @return[2]  nil
+-- @return[2] error message
+function mul1 () end
+
+-----
+-- function with return and  error tag
+-- @return  result
+-- @error message
+function mul2 () end
+
+-----
+-- function that raises an error.
+-- @string filename
+-- @treturn string result
+-- @raise 'file not found'
+function mul3(filename) end